MDL-21695 new help api
authorPetr Skoda <skodak@moodle.org>
Tue, 13 Apr 2010 21:51:49 +0000 (21:51 +0000)
committerPetr Skoda <skodak@moodle.org>
Tue, 13 Apr 2010 21:51:49 +0000 (21:51 +0000)
help.php
lib/formslib.php
lib/javascript-static.js
lib/outputcomponents.php
lib/outputrenderers.php

index 892fc66..eb88b48 100644 (file)
--- a/help.php
+++ b/help.php
@@ -17,7 +17,8 @@ require_once('config.php');
 
 $identifier = required_param('identifier', PARAM_SAFEDIR);
 $component  = required_param('component', PARAM_SAFEDIR);
-$lang       = required_param('component', PARAM_LANG);
+$lang       = required_param('component', PARAM_LANG); // TODO: maybe split into separate scripts
+$ajax       = optional_param('ajax', 0, PARAM_BOOL);
 
 if (!$lang) {
     $lang = 'en';
@@ -25,12 +26,25 @@ if (!$lang) {
 
 $SESSION->lang = $lang; // does not actually modify session because we do not use cookies here
 
-// send basic headers only, we do not need full html page here
-@header('Content-Type: text/plain; charset=utf-8');
+$sm = get_string_manager();
 
-if (strpos('_hlp', $identifier) === false) {
-    echo '<strong>Old 1.9 style help files need to be converted to standard strings with "_hlp" suffix: '.$component.'/'.$identifier.'</strong>';
-    die;
+//TODO: this is a minimalistic help page, needs a lot more love 
+
+$PAGE->set_url('/help.php');
+$PAGE->set_pagelayout('popup'); // not really a popup because this page gets dispalyed directly only when JS disabled
+
+if ($ajax) {
+    @header('Content-Type: text/plain; charset=utf-8');
+} else {
+    echo $OUTPUT->header();
 }
 
-echo get_string($identifier, $component);
+if ($sm->string_exists($identifier.'_hlp', $component)) {
+    echo get_string($identifier.'_hlp', $component);
+} else {
+    echo "<p><strong>TODO</strong>: fix help for [{$identifier}_hlp, $component]</p>";
+}
+
+if (!$ajax) {
+    echo $OUTPUT->footer();
+}
index 3ac34a6..7ba7b94 100644 (file)
@@ -1360,19 +1360,24 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless {
     }
 
     /**
-     * Add a help button to element,
-     * only one button per element is allowed.
+     * Add a help button to element, only one button per element is allowed.
+     *
+     * There has to be two strings defined:
+     *   1/ get_string($identifier, $component) - the title of the help page
+     *   2/ get_string($identifier.'_hlp', $component) - the actual help page text
      *
      * @param string $elementname name of the element to add the item to
      * @param string $identifier
-     * @param string $title
      * @param string $component
      * @param string $linktext
+     * @param boolean $suppresscheck whether to throw an error if the element doesn't exist.
      * @return void
      */
-    function addHelpButton($elementname, $identifier, $title, $component = 'moodle', $linktext = '') {
+    function addHelpButton($elementname, $identifier, $component = 'moodle', $linktext = '', $suppresscheck = false) {
+        global $OUTPUT;
         if (array_key_exists($elementname, $this->_elementIndex)) {
-            $element->_helpbutton = $OUTPUT->old_help_icon($identifier, $title, $component, $linktext);
+            $element = $this->_elements[$this->_elementIndex[$elementname]];
+            $element->_helpbutton = $OUTPUT->help_icon($identifier, $component, $linktext);
         } else if (!$suppresscheck) {
             debugging(get_string('nonexistentformelements', 'form', $elementname));
         }
index fc6dc19..3758d0e 100644 (file)
@@ -204,7 +204,7 @@ M.util.init_help_icons = function(Y) {
 
                 var link = context.getElementsByTagName('a')[0];
                 var thistooltip = this;
-                var ajaxurl = link.href + '&fortooltip=1';
+                var ajaxurl = link.href + '&ajax=1';
 
 
                 var cfg = {
index abf6305..05bfb9c 100644 (file)
@@ -217,13 +217,26 @@ class help_icon implements renderable {
     /**
      * Constructor
      * @param string $identifier  string for help page title,
-     *  string with _hlp suffix is used for the actual help text. 
+     *  string with _hlp suffix is used for the actual help text.
      * @param string $component
      */
-    public function __construct($pidentifier, $component) {
-        $this->identifier = $helpidentifier;
+    public function __construct($identifier, $component) {
+        $this->identifier = $identifier;
         $this->component  = $component;
     }
+
+    /**
+     * Verifies that both help strings exists, shows debug warnings if not
+     */
+    public function diag_strings() {
+        $sm = get_string_manager();
+        if (!$sm->string_exists($this->identifier, $this->component)) {
+            debugging("Help title string does not exist: [$this->identifier, $this->component]");
+        }
+        if (!$sm->string_exists($this->identifier.'_hlp', $this->component)) {
+            debugging("Help title string does not exist: [{$this->identifier}_hlp, $this->component]");
+        }
+    }
 }
 
 
@@ -458,7 +471,7 @@ class single_select implements renderable {
     }
 
     /**
-     * Constructor: sets up the other components in case they are needed
+     * Adds help icon.
      * @param string $page  The keyword that defines a help page
      * @param string $title A descriptive text for accesibility only
      * @param string $component
@@ -469,6 +482,17 @@ class single_select implements renderable {
         $this->helpicon = new old_help_icon($helppage, $title, $component);
     }
 
+    /**
+     * Adds help icon.
+     * @param string $identifier The keyword that defines a help page
+     * @param string $component
+     * @param bool $linktext add extra text to icon
+     * @return void
+     */
+    public function set_help_icon($identifier, $component = 'moodle') {
+        $this->helpicon = new old_help_icon($identifier, $component);
+    }
+
     /**
      * Set's select lable
      * @param string $label
@@ -555,7 +579,7 @@ class url_select implements renderable {
     }
 
     /**
-     * Constructor: sets up the other components in case they are needed
+     * Adds help icon.
      * @param string $page  The keyword that defines a help page
      * @param string $title A descriptive text for accesibility only
      * @param string $component
@@ -566,6 +590,17 @@ class url_select implements renderable {
         $this->helpicon = new old_help_icon($helppage, $title, $component);
     }
 
+    /**
+     * Adds help icon.
+     * @param string $identifier The keyword that defines a help page
+     * @param string $component
+     * @param bool $linktext add extra text to icon
+     * @return void
+     */
+    public function set_help_icon($identifier, $component = 'moodle') {
+        $this->helpicon = new _help_icon($identifier, $component);
+    }
+
     /**
      * Set's select lable
      * @param string $label
index 96952b2..fc92670 100644 (file)
@@ -1092,6 +1092,8 @@ class core_renderer extends renderer_base {
 
         if ($select->helpicon instanceof help_icon) {
             $output .= $this->render($select->helpicon);
+        } else if ($select->helpicon instanceof old_help_icon) {
+            $output .= $this->render($select->helpicon);
         }
 
         $output .= html_writer::select($select->options, $select->name, $select->selected, $select->nothing, $select->attributes);
@@ -1159,6 +1161,8 @@ class core_renderer extends renderer_base {
 
         if ($select->helpicon instanceof help_icon) {
             $output .= $this->render($select->helpicon);
+        } else if ($select->helpicon instanceof old_help_icon) {
+            $output .= $this->render($select->helpicon);
         }
 
         $output .= html_writer::empty_tag('input', array('type'=>'hidden', 'name'=>'sesskey', 'value'=>sesskey()));
@@ -1355,7 +1359,10 @@ END;
             $image = $this->pix_icon($icon, $iconalt, $component, array('class'=>'icon'));
         }
 
-        $help = $this->old_help_icon($helpidentifier, $text, $component);
+        $help = '';
+        if ($helpidentifier) {
+            $help = $this->help_icon($helpidentifier, $component);
+        }
 
         return $this->heading($image.$text.$help, 2, 'main help');
     }
@@ -1421,6 +1428,69 @@ END;
         return html_writer::tag('span', $output, array('class' => 'helplink'));
     }
 
+    /**
+     * Print a help icon.
+     *
+     * @param string $identifier The keyword that defines a help page
+     * @param string $component component name
+     * @param string|bool $linktext true means use $title as link text, string means link text value
+     * @return string HTML fragment
+     */
+    public function help_icon($identifier, $component = 'moodle', $linktext = '') {
+        $icon = new help_icon($identifier, $component);
+        $icon->diag_strings();
+        if ($linktext === true) {
+            $icon->linktext = get_string($icon->identifier, $icon->component);
+        } else if (!empty($linktext)) {
+            $icon->linktext = $linktext;
+        }
+        return $this->render($icon);
+    }
+
+    /**
+     * Implementation of user image rendering.
+     * @param help_icon $helpicon
+     * @return string HTML fragment
+     */
+    protected function render_help_icon(help_icon $helpicon) {
+        global $CFG;
+
+        // first get the help image icon
+        $src = $this->pix_url('help');
+
+        $title = get_string($helpicon->identifier, $helpicon->component);
+
+        if (empty($helpicon->linktext)) {
+            $alt = $title;
+        } else {
+            $alt = get_string('helpwiththis');
+        }
+
+        $attributes = array('src'=>$src, 'alt'=>$alt, 'class'=>'iconhelp');
+        $output = html_writer::empty_tag('img', $attributes);
+
+        // add the link text if given
+        if (!empty($helpicon->linktext)) {
+            // the spacing has to be done through CSS
+            $output .= $helpicon->linktext;
+        }
+
+        // now create the link around it
+        $url = new moodle_url('/help.php', array('component' => $helpicon->component, 'identifier' => $helpicon->identifier, 'lang'=>current_language()));
+
+        // note: this title is displayed only if JS is disabled, otherwise the link will have the new ajax tooltip
+        $title = get_string('helpprefix2', '', trim($title, ". \t"));
+
+        $attributes = array('href'=>$url, 'title'=>$title);
+        $id = html_writer::random_id('helpicon');
+        $attributes['id'] = $id;
+        $this->add_action_handler(new popup_action('click', $url), $id);
+        $output = html_writer::tag('a', $output, $attributes);
+
+        // and finally span
+        return html_writer::tag('span', $output, array('class' => 'helplink'));
+    }
+
     /**
      * Print scale help icon.
      *