help.php

   1 <?php
   2 /**
   3  * help.php - Displays help page.
   4  *
   5  * Prints a very simple page and includes
   6  * page content or a string from elsewhere.
   7  * Usually this will appear in a popup
   8  * See {@link helpbutton()} in {@link lib/moodlelib.php}
   9  *
  10  * @author Martin Dougiamas
  11  * @version $Id$
  12  * @package moodlecore
  13  */
  14 require_once('config.php');
  15
  16 // Get URL parameters.
  17 $file   = optional_param('file', '', PARAM_PATH);
  18 $text   = optional_param('text', 'No text to display', PARAM_CLEAN);
  19 $module = optional_param('module', 'moodle', PARAM_ALPHAEXT);
  20 $forcelang = optional_param('forcelang', '', PARAM_SAFEDIR);
  21 $skiplocal = optional_param('skiplocal', 0, PARAM_INT);     // shall _local help files be skipped?
  22
  23 // Start the output.
  24 print_header(get_string('help'));
  25 print_simple_box_start();
  26
  27 // We look for the help to display in lots of different places, and
  28 // only display an error at the end if we can't find the help file
  29 // anywhere. This variable tracks that.
  30 $helpfound = false;
  31
  32 if (!empty($file)) {
  33     // The help to display is from a help file.
  34
  35     // Get the list of parent languages.
  36     if (empty($forcelang)) {
  37         $langs = array(current_language(), get_string('parentlanguage'), 'en_utf8');  // Fallback
  38     } else {
  39         $langs = array($forcelang, 'en_utf8');
  40     }
  41
  42     if (!$skiplocal) {
  43         // _local language packs take precedence with both forced language and non-forced language settings
  44         $xlangs = array();
  45         foreach ($langs as $lang) {
  46             if (!empty($lang)) {
  47                 $xlangs[] = $lang . '_local';
  48                 $xlangs[] = $lang;
  49             }
  50         }
  51         $langs = $xlangs;
  52         unset($xlangs);
  53     }
  54
  55 // Define possible locations for help file similar to locations for language strings
  56 // Note: Always retain module directory as before
  57     $locations = array();
  58     if ($module == 'moodle') {
  59         $locations[$CFG->dataroot.'/lang/'] = $file;
  60         $locations[$CFG->dirroot.'/lang/'] = $file;
  61     } else {
  62         $modfile = $module.'/'.$file;
  63         $locations[$CFG->dataroot.'/lang/'] = $modfile;
  64         $locations[$CFG->dirroot.'/lang/'] = $modfile;
  65
  66         $rules = places_to_search_for_lang_strings();
  67         $exceptions = $rules['__exceptions'];
  68         unset($rules['__exceptions']);
  69
  70         if (!in_array($module, $exceptions)) {
  71             $dividerpos = strpos($module, '_');
  72             if ($dividerpos === false) {
  73                 $type = '';
  74                 $plugin = $module;
  75             } else {
  76                 $type = substr($module, 0, $dividerpos + 1);
  77                 $plugin = substr($module, $dividerpos + 1);
  78             }
  79             if (!empty($rules[$type])) {
  80                 foreach ($rules[$type] as $location) {
  81                     $locations[$CFG->dirroot . "/$location/$plugin/lang/"] = "$plugin/$file";
  82                 }
  83             }
  84         }
  85     }
  86
  87     // Work through the possible languages, starting with the most specific.
  88     while (!$helpfound && (list(,$lang) = each($langs)) && !empty($lang)) {
  89
  90         while (!$helpfound && (list($locationprefix,$locationsuffix) = each($locations))) {
  91             $filepath = $locationprefix.$lang.'/help/'.$locationsuffix;
  92
  93             // Now, try to include the help text from this file, if we can.
  94             if (file_exists_and_readable($filepath)) {
  95                 $helpfound = true;
  96                 @include($filepath);   // The actual helpfile
  97
  98                 // Now, we process some special cases.
  99                 $helpdir = $locationprefix.$lang.'/help';
 100                 if ($module == 'moodle' and ($file == 'index.html' or $file == 'mods.html')) {
 101                     include_help_for_each_module($file, $langs, $helpdir);
 102                 }
 103
 104                 // The remaining horrible hardcoded special cases should be delegated to modules somehow.
 105                 if ($module == 'moodle' and ($file == 'resource/types.html')) {  // RESOURCES
 106                     include_help_for_each_resource($file, $langs, $helpdir);
 107                 }
 108                 if ($module == 'moodle' and ($file == 'assignment/types.html')) {  // ASSIGNMENTS
 109                     include_help_for_each_assignment_type();
 110                 }
 111             }
 112         }
 113         reset($locations);
 114     }
 115 } else {
 116     // The help to display was given as an argument to this function.
 117     echo '<p>'.s($text).'</p>';   // This param was already cleaned
 118     $helpfound = true;
 119 }
 120
 121 print_simple_box_end();
 122
 123 // Display an error if necessary.
 124 if (!$helpfound) {
 125     notify('Help file "'. $file .'" could not be found!');
 126 }
 127
 128 // End of page.
 129 close_window_button();
 130 echo '<p class="helpindex"><a href="help.php?file=index.html">'. get_string('helpindex') .'</a></p>';
 131
 132 $CFG->docroot = '';   // We don't want a doc link here
 133 print_footer('none');
 134
 135 // Utility function =================================================================
 136
 137 function file_exists_and_readable($filepath) {
 138     return file_exists($filepath) and is_file($filepath) and is_readable($filepath);
 139 }
 140
 141 // Some functions for handling special cases ========================================
 142
 143 function include_help_for_each_module($file, $langs, $helpdir) {
 144     global $CFG;
 145
 146     if (!$modules = get_records('modules', 'visible', 1)) {
 147         error('No modules found!!');        // Should never happen
 148     }
 149
 150     foreach ($modules as $mod) {
 151         $strmodulename = get_string('modulename', $mod->name);
 152         $modulebyname[$strmodulename] = $mod;
 153     }
 154     ksort($modulebyname, SORT_LOCALE_STRING);
 155
 156     foreach ($modulebyname as $mod) {
 157         foreach ($langs as $lang) {
 158             if (empty($lang)) {
 159                 continue;
 160             }
 161
 162             $filepath = "$helpdir/$mod->name/$file";
 163
 164             // If that does not exist, try a fallback into the module code folder.
 165             if (!file_exists($filepath)) {
 166                 $filepath = "$CFG->dirroot/mod/$mod->name/lang/$lang/help/$mod->name/$file";
 167             }
 168
 169             if (file_exists_and_readable($filepath)) {
 170                 echo '<hr />';
 171                 @include($filepath); // The actual helpfile
 172                 break; // Out of loop over languages.
 173             }
 174         }
 175     }
 176 }
 177
 178 function include_help_for_each_resource($file, $langs, $helpdir) {
 179     global $CFG;
 180
 181     require_once($CFG->dirroot .'/mod/resource/lib.php');
 182     $typelist = resource_get_types();
 183     $typelist['label'] = get_string('resourcetypelabel', 'resource');
 184
 185     foreach ($typelist as $type => $name) {
 186         foreach ($langs as $lang) {
 187             if (empty($lang)) {
 188                 continue;
 189             }
 190
 191             $filepath = "$helpdir/resource/type/$type.html";
 192
 193             if (file_exists_and_readable($filepath)) {
 194                 echo '<hr size="1" />';
 195                 @include($filepath); // The actual helpfile
 196                 break; // Out of loop over languages.
 197             }
 198         }
 199     }
 200 }
 201
 202 function include_help_for_each_assignment_type() {
 203     global $CFG;
 204
 205     require_once($CFG->dirroot .'/mod/assignment/lib.php');
 206     $typelist = assignment_types();
 207
 208     foreach ($typelist as $type => $name) {
 209         echo '<p><b>'.$name.'</b></p>';
 210         echo get_string('help'.$type, 'assignment');
 211         echo '<hr size="1" />';
 212     }
 213 }
 214 ?>