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();
  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         if (strpos($module, 'block_') === 0) {  // It's a block help file
  65             $block = substr($module, 6);
  66             $locations[$CFG->dirroot .'/blocks/'.$block.'/lang/'] =  $block.'/'.$file;
  67         } else if (strpos($module, 'report_') === 0) {  // It's a report help file
  68             $report = substr($module, 7);
  69             $locations[$CFG->dirroot .'/'.$CFG->admin.'/report/'.$report.'/lang/'] = $report.'/'.$file;
  70             $locations[$CFG->dirroot .'/course/report/'.$report.'/lang/'] = $report.'/'.$file;
  71         } else if (strpos($module, 'format_') === 0) {  // Course format
  72             $format = substr($module,7);
  73             $locations[$CFG->dirroot  .'/course/format/'.$format.'/lang/'] = $format.'/'.$file;
  74         } else {                                // It's a normal activity
  75             $locations[$CFG->dirroot .'/mod/'.$module.'/lang/'] = $module.'/'.$file;
  76         }
  77     }
  78
  79     // Work through the possible languages, starting with the most specific.
  80     while (!$helpfound && (list(,$lang) = each($langs)) && !empty($lang)) {
  81
  82         while (!$helpfound && (list($locationprefix,$locationsuffix) = each($locations))) {
  83             $filepath = $locationprefix.$lang.'/help/'.$locationsuffix;
  84
  85             // Now, try to include the help text from this file, if we can.
  86             if (file_exists_and_readable($filepath)) {
  87                 $helpfound = true;
  88                 @include($filepath);   // The actual helpfile
  89
  90                 // Now, we process some special cases.
  91                 $helpdir = $locationprefix.$lang.'/help';
  92                 if ($module == 'moodle' and ($file == 'index.html' or $file == 'mods.html')) {
  93                     include_help_for_each_module($file, $langs, $helpdir);
  94                 }
  95
  96                 // The remaining horrible hardcoded special cases should be delegated to modules somehow.
  97                 if ($module == 'moodle' and ($file == 'resource/types.html')) {  // RESOURCES
  98                     include_help_for_each_resource($file, $langs, $helpdir);
  99                 }
 100                 if ($module == 'moodle' and ($file == 'assignment/types.html')) {  // ASSIGNMENTS
 101                     include_help_for_each_assignment_type();
 102                 }
 103             }
 104         }
 105         reset($locations);
 106     }
 107 } else {
 108     // The help to display was given as an argument to this function.
 109     echo '<p>'.s($text).'</p>';   // This param was already cleaned
 110     $helpfound = true;
 111 }
 112
 113 print_simple_box_end();
 114
 115 // Display an error if necessary.
 116 if (!$helpfound) {
 117     notify('Help file "'. $file .'" could not be found!');
 118 }
 119
 120 // End of page.
 121 close_window_button();
 122 echo '<p class="helpindex"><a href="help.php?file=index.html">'. get_string('helpindex') .'</a></p>';
 123
 124 $CFG->docroot = '';   // We don't want a doc link here
 125 print_footer('none');
 126
 127 // Utility function =================================================================
 128
 129 function file_exists_and_readable($filepath) {
 130     return file_exists($filepath) and is_file($filepath) and is_readable($filepath);
 131 }
 132
 133 // Some functions for handling special cases ========================================
 134
 135 function include_help_for_each_module($file, $langs, $helpdir) {
 136     global $CFG;
 137
 138     if (!$modules = get_records('modules', 'visible', 1)) {
 139         error('No modules found!!');        // Should never happen
 140     }
 141
 142     foreach ($modules as $mod) {
 143         $strmodulename = get_string('modulename', $mod->name);
 144         $modulebyname[$strmodulename] = $mod;
 145     }
 146     ksort($modulebyname);
 147
 148     foreach ($modulebyname as $mod) {
 149         foreach ($langs as $lang) {
 150             if (empty($lang)) {
 151                 continue;
 152             }
 153
 154             $filepath = "$helpdir/$mod->name/$file";
 155
 156             // If that does not exist, try a fallback into the module code folder.
 157             if (!file_exists($filepath)) {
 158                 $filepath = "$CFG->dirroot/mod/$mod->name/lang/$lang/help/$mod->name/$file";
 159             }
 160
 161             if (file_exists_and_readable($filepath)) {
 162                 echo '<hr size="1" />';
 163                 @include($filepath); // The actual helpfile
 164                 break; // Out of loop over languages.
 165             }
 166         }
 167     }
 168 }
 169
 170 function include_help_for_each_resource($file, $langs, $helpdir) {
 171     global $CFG;
 172
 173     require_once($CFG->dirroot .'/mod/resource/lib.php');
 174     $typelist = resource_get_types();
 175     $typelist['label'] = get_string('resourcetypelabel', 'resource');
 176
 177     foreach ($typelist as $type => $name) {
 178         foreach ($langs as $lang) {
 179             if (empty($lang)) {
 180                 continue;
 181             }
 182
 183             $filepath = "$helpdir/resource/type/$type.html";
 184
 185             if (file_exists_and_readable($filepath)) {
 186                 echo '<hr size="1" />';
 187                 @include($filepath); // The actual helpfile
 188                 break; // Out of loop over languages.
 189             }
 190         }
 191     }
 192 }
 193
 194 function include_help_for_each_assignment_type() {
 195     global $CFG;
 196
 197     require_once($CFG->dirroot .'/mod/assignment/lib.php');
 198     $typelist = assignment_types();
 199
 200     foreach ($typelist as $type => $name) {
 201         echo '<p><b>'.$name.'</b></p>';
 202         echo get_string('help'.$type, 'assignment');
 203         echo '<hr size="1" />';
 204     }
 205 }
 206 ?>