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 $fortooltip = optional_param('fortooltip', 0, PARAM_INT);
  23
  24 $PAGE->set_course($COURSE);
  25
  26 $url = new moodle_url($CFG->wwwroot.'/help.php');
  27 if ($file !== '')  {
  28     $url->param('file', $file);
  29 }
  30 if ($text !== 'No text to display')  {
  31     $url->param('text', $text);
  32 }
  33 if ($module !== 'moodle')  {
  34     $url->param('module', $module);
  35 }
  36 if ($forcelang !== '')  {
  37     $url->param('forcelang', $forcelang);
  38 }
  39 if ($skiplocal !== 0)  {
  40     $url->param('skiplocal', $skiplocal);
  41 }
  42 if ($fortooltip !== 0)  {
  43     $url->param('fortooltip', $fortooltip);
  44 }
  45 $PAGE->set_url($url);
  46
  47 // We look for the help to display in lots of different places, and
  48 // only display an error at the end if we can't find the help file
  49 // anywhere. This variable tracks that.
  50 $helpfound = false;
  51
  52 // Buffer output so that we can examine it later to extract metadata (page title)
  53 ob_start();
  54
  55 if (!empty($file)) {
  56     // The help to display is from a help file.
  57     list($filepath, $foundlang) = string_manager::instance()->find_help_file($file, $module, $forcelang, $skiplocal);
  58
  59     if ($filepath) {
  60         $helpfound = true;
  61         @include($filepath);   // The actual helpfile
  62
  63         // Now, we process some special cases.
  64         if ($module == 'moodle' and ($file == 'index.html' or $file == 'mods.html')) {
  65             include_help_for_each_module($file, $forcelang, $skiplocal);
  66         }
  67         if ($module == 'question' && $file == 'types.html') {
  68             include_help_for_each_qtype();
  69         }
  70
  71         // The remaining horrible hardcoded special cases should be delegated to modules somehow.
  72         if ($module == 'moodle' && $file == 'assignment/types.html') {  // ASSIGNMENTS
  73             include_help_for_each_assignment_type($forcelang, $skiplocal);
  74         }
  75     }
  76 } else {
  77     // The help to display was given as an argument to this function.
  78     echo '<p>'.s($text).'</p>';   // This param was already cleaned
  79     $helpfound = true;
  80 }
  81
  82 // Finish buffer
  83 $output = ob_get_contents();
  84
  85 ob_end_clean();
  86
  87 if ($fortooltip) {
  88     echo shorten_text($output, 400, false, '<span class="readmore">' . get_string('clickhelpiconformoreinfo') . '</span>');
  89     die();
  90 }
  91
  92 // Determine title
  93 $title = get_string('help'); // Default is just 'Help'
  94 $matches = array();
  95 // You can include a <title> tag to override the standard behaviour:
  96 // 'Help - title contents'. Otherwise it looks for the text of the first
  97 // heading: 'Help - heading text'. If there aren't even any headings
  98 // you just get 'Help'
  99 if (preg_match('~^(.*?)<title>(.*?)</title>(.*)$~s', $output, $matches)) {
 100     // Extract title
 101     $title = $title.' - '.$matches[2];
 102     // Strip title from output
 103     $output = $matches[1].$matches[3];
 104 } else if(preg_match('~<h[0-9]+(\s[^>]*)?>(.*?)</h[0-9]+>~s',$output,$matches)) {
 105     // Use first heading as title (obviously leave it in output too). Strip
 106     // any tags from inside
 107     $matches[2] = preg_replace('~<[^>]*>~s','',$matches[2]);
 108     $title = $title.' - '.$matches[2];
 109 }
 110
 111 // use ##emoticons_html## to replace the emoticons documentation
 112 if(preg_match('~(##emoticons_html##)~', $output, $matches)) {
 113     $output = preg_replace('~(##emoticons_html##)~', get_emoticons_list_for_help_file(), $output);
 114 }
 115
 116 // Do the main output.
 117 $PAGE->set_generaltype('popup');
 118 $PAGE->set_title($title);
 119 echo $OUTPUT->header();
 120 echo $OUTPUT->box_start();
 121 print $output;
 122 echo $OUTPUT->box_end();
 123
 124 // Display an error if necessary.
 125 if (!$helpfound) {
 126     echo $OUTPUT->notification('Help file "'. $file .'" could not be found!');
 127 }
 128
 129 // End of page.
 130 echo $OUTPUT->close_window_button();
 131 echo '<p class="helpindex"><a href="help.php?file=index.html">'. get_string('helpindex') .'</a></p>';
 132
 133 // Offer a link to the alternative help file language
 134 $currentlang = current_language();
 135 if ($file && $helpfound && ($foundlang != 'en_utf8' || ($forcelang == 'en_utf8' && current_language() != 'en_utf8'))) {
 136     $url = new moodle_url();
 137     if ($foundlang != 'en_utf8') {
 138         $url->param('forcelang', 'en_utf8');
 139         $nextlangname = get_string('english');
 140     } else {
 141         $url->param('forcelang', $currentlang);
 142         $nextlangname = get_string('thislanguage');
 143     }
 144     echo '<p><a href="' . $url->out() . '">' . get_string('showthishelpinlanguage', 'moodle', $nextlangname) . '</a></p>';
 145 }
 146
 147 $CFG->docroot = '';   // We don't want a doc link here
 148 echo $OUTPUT->footer();
 149
 150 function file_exists_and_readable($filepath) {
 151     return file_exists($filepath) and is_file($filepath) and is_readable($filepath);
 152 }
 153
 154 // Some functions for handling special cases ========================================
 155
 156 function include_help_for_each_module($file, $forcelang, $skiplocal) {
 157     global $CFG, $DB;
 158
 159     if (!$modules = $DB->get_records('modules', array('visible'=> 1))) {
 160         print_error('nomodules', 'debug'); // Should never happen
 161     }
 162
 163     // Horrible hack to show the help about grades here too.
 164     $grade = new stdClass();
 165     $grade->name = 'grade';
 166     $modules[] = $grade;
 167
 168     foreach ($modules as $mod) {
 169         $strmodulename = get_string('modulename', $mod->name);
 170         $modulebyname[$strmodulename] = $mod;
 171     }
 172     ksort($modulebyname, SORT_LOCALE_STRING);
 173
 174     foreach ($modulebyname as $mod) {
 175         list($filepath, $foundlang) = string_manager::instance()->find_help_file($file, $mod->name, $forcelang, $skiplocal);
 176         if ($filepath) {
 177             echo '<hr />';
 178             include($filepath);
 179         }
 180     }
 181 }
 182
 183 function include_help_for_each_qtype() {
 184     global $CFG;
 185     require_once($CFG->libdir . '/questionlib.php');
 186     global $QTYPES;
 187     $types = question_type_menu();
 188     $fakeqtypes = array();
 189     foreach ($types as $qtype => $localizedname) {
 190         if ($QTYPES[$qtype]->is_real_question_type()) {
 191             include_help_for_qtype($qtype, $localizedname);
 192         } else {
 193             $fakeqtypes[$qtype] = $localizedname;
 194         }
 195     }
 196     foreach ($fakeqtypes as $qtype => $localizedname) {
 197         include_help_for_qtype($qtype, $localizedname);
 198     }
 199 }
 200 function include_help_for_qtype($qtype, $localizedname) {
 201     echo '<h2>' . $localizedname . "</h2>\n\n";
 202     echo '<p>' . get_string($qtype . 'summary', 'qtype_' . $qtype) . "</p>\n\n";
 203 }
 204
 205 function include_help_for_each_assignment_type() {
 206     global $CFG;
 207
 208     require_once($CFG->dirroot .'/mod/assignment/lib.php');
 209     $typelist = assignment_types();
 210
 211     foreach ($typelist as $type => $name) {
 212         echo '<h2>'.$name.'</h2>';
 213         echo get_string('help'.$type, 'assignment');
 214         echo '<hr />';
 215     }
 216 }
 217 ?>