MDL-21695 Display the help title in the popup, more docs on new addHe…

…lpButton()

help.php

@@ -1,29 +1,43 @@
 <?php
+
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * help.php - Displays help page.
+ * Displays help via AJAX call or in a new page
  *
- * Prints a very simple page and includes
- * page content or a string from elsewhere.
- * Usually this will appear in a popup
- * See {@link helpbutton()} in {@link lib/moodlelib.php}
+ * Use {@link core_renderer::help_icon()} or {@link addHelpButton()} to display
+ * the help icon.
  *
- * @author Martin Dougiamas
- * @package moodlecore
+ * @copyright 2002 onwards Martin Dougiamas
+ * @package   core
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 define('NO_MOODLE_COOKIES', true);
 
-require_once('config.php');
+require_once(dirname(__FILE__) . '/config.php');
 
-$identifier = required_param('identifier', PARAM_SAFEDIR);
+$identifier = required_param('identifier', PARAM_STRINGID);
 $component  = required_param('component', PARAM_SAFEDIR);
 $lang       = required_param('component', PARAM_LANG); // TODO: maybe split into separate scripts
 $ajax       = optional_param('ajax', 0, PARAM_BOOL);
 
 if (!$lang) {
     $lang = 'en';
 }
-
 $SESSION->lang = $lang; // does not actually modify session because we do not use cookies here
 
 $sm = get_string_manager();
@@ -47,8 +61,9 @@
     $options->para = true;
     $options->newlines = false;
 
+    echo $OUTPUT->heading(format_string(get_string($identifier, $component)), 1, 'helpheading');
     // Should be simple wiki only MDL-21695
-    echo format_text(get_string($identifier.'_help', $component), FORMAT_MOODLE, $options);  
+    echo format_text(get_string($identifier.'_help', $component), FORMAT_MOODLE, $options);
 
     if ($sm->string_exists($identifier.'_link', $component)) {  // Link to further info in Moodle docs
         $link = get_string($identifier.'_link', $component);
@@ -57,7 +72,7 @@
     }
 
 } else {
-    echo "<p><strong>TODO</strong>: fix help for [{$identifier}_help, $component]</p>";
+    echo "<p><strong>TODO</strong>: missing help string [{$identifier}_help, $component]</p>";
 }
 
 if (!$ajax) {

lib/formslib.php

@@ -1327,6 +1327,7 @@ function setHelpButtons($buttons, $suppresscheck=false, $function='helpbutton'){
     /**
      * Add a single button.
      *
+     * @deprecated use addHelpButton() instead
      * @param string $elementname name of the element to add the item to
      * @param array $button arguments to pass to function $function
      * @param boolean $suppresscheck whether to throw an error if the element
@@ -1362,15 +1363,23 @@ function setHelpButton($elementname, $buttonargs, $suppresscheck=false, $functio
     /**
      * Add a help button to element, only one button per element is allowed.
      *
+     * This is new, simplified and preferable method of setting a help icon on form elements.
+     * It uses the new $OUTPUT->help_icon().
+     *
+     * Typically, you will provide the same identifier and the component as you have used for the
+     * label of the element. The string identifier with the _help suffix added is then used
+     * as the help string.
+     *
      * There has to be two strings defined:
      *   1/ get_string($identifier, $component) - the title of the help page
      *   2/ get_string($identifier.'_help', $component) - the actual help page text
      *
+     * @since 2.0
      * @param string $elementname name of the element to add the item to
-     * @param string $identifier
-     * @param string $component
-     * @param string $linktext
-     * @param boolean $suppresscheck whether to throw an error if the element doesn't exist.
+     * @param string $identifier help string identifer without _help suffix
+     * @param string $component component name to look the help string in
+     * @param string $linktext optional text to display next to the icon
+     * @param boolean $suppresscheck set to true if the element may not exist
      * @return void
      */
     function addHelpButton($elementname, $identifier, $component = 'moodle', $linktext = '', $suppresscheck = false) {