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>';
 131
 132 // Offer a link to the alternative help file language
 133 if (($helpfound) and (((current_language() != 'en_utf8') and $lang != 'en_utf8') or ($forcelang === 'en_utf8'))) {
 134     $linklang = "{$CFG->wwwroot}/help.php?";
 135     $linklang .= !empty($module)    ? "module=$module&amp;" : '';
 136     $linklang .= !empty($file)      ? "file=$file&amp;" : '';
 137     $linklang .= !empty($skiplocal) ? "skiplocal=$skiplocal&amp;" : '';
 138
 139     if (empty($forcelang) or $forcelang === current_language()) {
 140         $nextlang = 'en_utf8';
 141         $nextlangname = 'English';
 142     } else {
 143         $nextlang = current_language();
 144         $nextlangname = get_string('thislanguage');
 145     }
 146
 147     $linklang .= "forcelang=$nextlang";
 148     echo "<br /><a href=\"$linklang\">" . get_string('showthishelpinlanguage', 'moodle', $nextlangname) . '</a>';
 149 }
 150 echo '</p>';
 151
 152 $CFG->docroot = '';   // We don't want a doc link here
 153 print_footer('none');
 154
 155 // Utility function =================================================================
 156
 157 function file_exists_and_readable($filepath) {
 158     return file_exists($filepath) and is_file($filepath) and is_readable($filepath);
 159 }
 160
 161 // Some functions for handling special cases ========================================
 162
 163 function include_help_for_each_module($file, $langs, $helpdir) {
 164     global $CFG;
 165
 166     if (!$modules = get_records('modules', 'visible', 1)) {
 167         error('No modules found!!');        // Should never happen
 168     }
 169
 170     foreach ($modules as $mod) {
 171         $strmodulename = get_string('modulename', $mod->name);
 172         $modulebyname[$strmodulename] = $mod;
 173     }
 174     ksort($modulebyname, SORT_LOCALE_STRING);
 175
 176     foreach ($modulebyname as $mod) {
 177         foreach ($langs as $lang) {
 178             if (empty($lang)) {
 179                 continue;
 180             }
 181
 182             $filepath = "$helpdir/$mod->name/$file";
 183
 184             // If that does not exist, try a fallback into the module code folder.
 185             if (!file_exists($filepath)) {
 186                 $filepath = "$CFG->dirroot/mod/$mod->name/lang/$lang/help/$mod->name/$file";
 187             }
 188
 189             if (file_exists_and_readable($filepath)) {
 190                 echo '<hr />';
 191                 @include($filepath); // The actual helpfile
 192                 break; // Out of loop over languages.
 193             }
 194         }
 195     }
 196 }
 197
 198 function include_help_for_each_resource($file, $langs, $helpdir) {
 199     global $CFG;
 200
 201     require_once($CFG->dirroot .'/mod/resource/lib.php');
 202     $typelist = resource_get_types();
 203
 204     //add label type
 205     $labelType = new object();
 206     $labelType->modclass = MOD_CLASS_RESOURCE;
 207     $resourcetype = 'label';
 208     $labelType->name = $resourcetype;
 209     $labelType->type = "resource&amp;type=$resourcetype";
 210     $labelType->typestr = get_string("resourcetype$resourcetype", 'resource');
 211     $typelist[] = $labelType;
 212
 213     foreach ($typelist as $type) {
 214
 215         foreach ($langs as $lang) {
 216             if (empty($lang)) {
 217                 continue;
 218             }
 219
 220             $filepath = "$helpdir/resource/type/".$type->name.".html";
 221
 222             if (file_exists_and_readable($filepath)) {
 223                 echo '<hr />';
 224                 @include($filepath); // The actual helpfile
 225                 break; // Out of loop over languages.
 226             }
 227         }
 228     }
 229 }
 230
 231 function include_help_for_each_assignment_type() {
 232     global $CFG;
 233
 234     require_once($CFG->dirroot .'/mod/assignment/lib.php');
 235     $typelist = assignment_types();
 236
 237     foreach ($typelist as $type => $name) {
 238         echo '<p><b>'.$name.'</b></p>';
 239         echo get_string('help'.$type, 'assignment');
 240         echo '<hr size="1" />';
 241     }
 242 }
 243 ?>