lib/form/group.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17
  18 /**
  19  * Form element group
  20  *
  21  * Contains HTML class for group form element
  22  *
  23  * @package   core_form
  24  * @copyright 2007 Jamie Pratt <me@jamiep.org>
  25  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  26  */
  27
  28 require_once("HTML/QuickForm/group.php");
  29 require_once('templatable_form_element.php');
  30
  31 /**
  32  * HTML class for a form element group
  33  *
  34  * Overloaded {@link HTML_QuickForm_group} with default behavior modified for Moodle.
  35  *
  36  * @package   core_form
  37  * @category  form
  38  * @copyright 2007 Jamie Pratt <me@jamiep.org>
  39  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  40  */
  41 class MoodleQuickForm_group extends HTML_QuickForm_group implements templatable {
  42     use templatable_form_element {
  43         export_for_template as export_for_template_base;
  44     }
  45
  46     /** @var string html for help button, if empty then no help */
  47     var $_helpbutton='';
  48
  49     /** @var bool if true label will be hidden. */
  50     protected $_hiddenLabel = false;
  51
  52     /** @var MoodleQuickForm */
  53     protected $_mform = null;
  54
  55     protected $_renderedfromtemplate = false;
  56
  57     /**
  58      * constructor
  59      *
  60      * @param string $elementName (optional) name of the group
  61      * @param string $elementLabel (optional) group label
  62      * @param array $elements (optional) array of HTML_QuickForm_element elements to group
  63      * @param string|array $separator (optional) Use a string for one separator, or use an array to alternate the separators
  64      * @param string $appendName (optional) string to appened to grouped elements.
  65      * @param mixed $attributes (optional) Either a typical HTML attribute string
  66      *              or an associative array
  67      */
  68     public function __construct(
  69         $elementName = null,
  70         $elementLabel = null,
  71         $elements = null,
  72         $separator = null,
  73         $appendName = true,
  74         $attributes = null
  75     ) {
  76         parent::__construct($elementName, $elementLabel, $elements, $separator, $appendName, $attributes);
  77     }
  78
  79     /**
  80      * Old syntax of class constructor. Deprecated in PHP7.
  81      *
  82      * @deprecated since Moodle 3.1
  83      */
  84     public function MoodleQuickForm_group($elementName=null, $elementLabel=null, $elements=null, $separator=null, $appendName = true) {
  85         debugging('Use of class name as constructor is deprecated', DEBUG_DEVELOPER);
  86         self::__construct($elementName, $elementLabel, $elements, $separator, $appendName);
  87     }
  88
  89     /** @var string template type, would cause problems with client side validation so will leave for now */
  90     //var $_elementTemplateType='fieldset';
  91
  92     /**
  93      * set html for help button
  94      */
  95     function getHelpButton(){
  96         return $this->_helpbutton;
  97     }
  98
  99     /**
 100      * Returns element template, nodisplay/static/fieldset
 101      *
 102      * @return string
 103      */
 104     function getElementTemplateType(){
 105         if ($this->_flagFrozen){
 106             if ($this->getGroupType() == 'submit'){
 107                 return 'nodisplay';
 108             } else {
 109                 return 'static';
 110             }
 111         } else {
 112             if ($this->getGroupType() == 'submit') {
 113                 return 'actionbuttons';
 114             }
 115             return 'fieldset';
 116         }
 117     }
 118
 119     /**
 120      * Sets label to be hidden
 121      *
 122      * @param bool $hiddenLabel sets if label should be hidden
 123      */
 124     public function setHiddenLabel($hiddenLabel) {
 125         $this->_hiddenLabel = $hiddenLabel;
 126     }
 127
 128     /**
 129      * Sets the grouped elements and hides label
 130      *
 131      * @param array $elements
 132      */
 133     function setElements($elements){
 134         parent::setElements($elements);
 135         foreach ($this->_elements as $element){
 136             if (method_exists($element, 'setHiddenLabel')){
 137                 $element->setHiddenLabel(true);
 138             }
 139         }
 140     }
 141
 142     /**
 143      * Stores the form this element was added to
 144      * This object is later used by {@link MoodleQuickForm_group::createElement()}
 145      * @param null|MoodleQuickForm $mform
 146      */
 147     public function setMoodleForm($mform) {
 148         if ($mform && $mform instanceof MoodleQuickForm) {
 149             $this->_mform = $mform;
 150         }
 151     }
 152
 153     /**
 154      * Called by HTML_QuickForm whenever form event is made on this element
 155      *
 156      * If this function is overridden and parent is not called the element must be responsible for
 157      * storing the MoodleQuickForm object, see {@link MoodleQuickForm_group::setMoodleForm()}
 158      *
 159      * @param     string $event Name of event
 160      * @param     mixed $arg event arguments
 161      * @param     mixed $caller calling object
 162      * @return    ?bool
 163      */
 164     public function onQuickFormEvent($event, $arg, &$caller) {
 165         $this->setMoodleForm($caller);
 166         return parent::onQuickFormEvent($event, $arg, $caller);
 167     }
 168
 169     /**
 170      * Creates an element to add to the group
 171      * Expects the same arguments as MoodleQuickForm::createElement()
 172      */
 173     public function createFormElement() {
 174         if (!$this->_mform) {
 175             throw new coding_exception('You can not call createFormElement() on the group element that was not yet added to a form.');
 176         }
 177         return call_user_func_array([$this->_mform, 'createElement'], func_get_args());
 178     }
 179
 180     /**
 181      * Return attributes suitable for passing to {@see createFormElement}, comprised of all group attributes without ID in
 182      * order to ensure uniqueness of that value within the group
 183      *
 184      * @return array
 185      */
 186     public function getAttributesForFormElement(): array {
 187         return array_diff_key((array) $this->getAttributes(), array_flip(['id']));
 188     }
 189
 190     public function export_for_template(renderer_base $output) {
 191         global $OUTPUT;
 192
 193         $context = $this->export_for_template_base($output);
 194
 195         $this->_renderedfromtemplate = true;
 196
 197         include_once('HTML/QuickForm/Renderer/Default.php');
 198
 199         $elements = [];
 200         $name = $this->getName();
 201         $i = 0;
 202         foreach ($this->_elements as $key => $element) {
 203             $elementname = '';
 204             if ($this->_appendName) {
 205                 $elementname = $element->getName();
 206                 if (isset($elementname)) {
 207                     $element->setName($name . '['. (strlen($elementname) ? $elementname : $key) .']');
 208                 } else {
 209                     $element->setName($name);
 210                 }
 211             }
 212             $element->_generateId();
 213
 214             $out = $OUTPUT->mform_element($element, false, false, '', true);
 215
 216             if (empty($out)) {
 217                 $renderer = new HTML_QuickForm_Renderer_Default();
 218                 $renderer->setElementTemplate('{element}');
 219                 $element->accept($renderer);
 220                 $out = $renderer->toHtml();
 221             }
 222
 223             // Replicates the separator logic from 'pear/HTML/QuickForm/Renderer/Default.php'.
 224             $separator = '';
 225             if ($i > 0) {
 226                 if (is_array($this->_separator)) {
 227                     $separator = $this->_separator[($i - 1) % count($this->_separator)];
 228                 } else if ($this->_separator === null) {
 229                     $separator = '&nbsp;';
 230                 } else {
 231                     $separator = (string) $this->_separator;
 232                 }
 233             }
 234
 235             $elements[] = [
 236                 'separator' => $separator,
 237                 'html' => $out
 238             ];
 239
 240             // Restore the element's name.
 241             if ($this->_appendName) {
 242                 $element->setName($elementname);
 243             }
 244
 245             $i++;
 246         }
 247
 248         $context['groupname'] = $name;
 249         $context['elements'] = $elements;
 250         return $context;
 251     }
 252
 253     /**
 254      * Accepts a renderer
 255      *
 256      * @param object     An HTML_QuickForm_Renderer object
 257      * @param bool       Whether a group is required
 258      * @param string     An error message associated with a group
 259      * @access public
 260      * @return void
 261      */
 262     public function accept(&$renderer, $required = false, $error = null) {
 263         $this->_createElementsIfNotExist();
 264         $renderer->startGroup($this, $required, $error);
 265         if (!$this->_renderedfromtemplate) {
 266             // Backwards compatible path - only do this if we didn't render the sub-elements already.
 267             $name = $this->getName();
 268             foreach (array_keys($this->_elements) as $key) {
 269                 $element =& $this->_elements[$key];
 270                 $elementname = '';
 271                 if ($this->_appendName) {
 272                     $elementname = $element->getName();
 273                     if (isset($elementname)) {
 274                         $element->setName($name . '['. (strlen($elementname) ? $elementname : $key) .']');
 275                     } else {
 276                         $element->setName($name);
 277                     }
 278                 }
 279
 280                 $required = !$element->isFrozen() && in_array($element->getName(), $this->_required);
 281
 282                 $element->accept($renderer, $required);
 283
 284                 // Restore the element's name.
 285                 if ($this->_appendName) {
 286                     $element->setName($elementname);
 287                 }
 288             }
 289         }
 290         $renderer->finishGroup($this);
 291     }
 292
 293     /**
 294      * Calls the validateSubmitValue function for the containing elements and returns an error string as soon as it finds one.
 295      *
 296      * @param array $values Values of the containing elements.
 297      * @return string|null Validation error message or null.
 298      */
 299     public function validateSubmitValue($values) {
 300         foreach ($this->_elements as $element) {
 301             if (method_exists($element, 'validateSubmitValue')) {
 302                 $value = $values[$element->getName()] ?? null;
 303                 $result = $element->validateSubmitValue($value);
 304                 if (!empty($result) && is_string($result)) {
 305                     return $result;
 306                 }
 307             }
 308         }
 309     }
 310 }