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