Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
/lib/form/ -> group.php (source)

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 402 and 403]

   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 MoodleQuickForm */
  50      protected $_mform = null;
  51  
  52      protected $_renderedfromtemplate = false;
  53  
  54      /**
  55       * constructor
  56       *
  57       * @param string $elementName (optional) name of the group
  58       * @param string $elementLabel (optional) group label
  59       * @param array $elements (optional) array of HTML_QuickForm_element elements to group
  60       * @param string $separator (optional) string to seperate elements.
  61       * @param string $appendName (optional) string to appened to grouped elements.
  62       */
  63      public function __construct($elementName=null, $elementLabel=null, $elements=null, $separator=null, $appendName = true) {
  64          parent::__construct($elementName, $elementLabel, $elements, $separator, $appendName);
  65      }
  66  
  67      /**
  68       * Old syntax of class constructor. Deprecated in PHP7.
  69       *
  70       * @deprecated since Moodle 3.1
  71       */
  72      public function MoodleQuickForm_group($elementName=null, $elementLabel=null, $elements=null, $separator=null, $appendName = true) {
  73          debugging('Use of class name as constructor is deprecated', DEBUG_DEVELOPER);
  74          self::__construct($elementName, $elementLabel, $elements, $separator, $appendName);
  75      }
  76  
  77      /** @var string template type, would cause problems with client side validation so will leave for now */
  78      //var $_elementTemplateType='fieldset';
  79  
  80      /**
  81       * set html for help button
  82       */
  83      function getHelpButton(){
  84          return $this->_helpbutton;
  85      }
  86  
  87      /**
  88       * Returns element template, nodisplay/static/fieldset
  89       *
  90       * @return string
  91       */
  92      function getElementTemplateType(){
  93          if ($this->_flagFrozen){
  94              if ($this->getGroupType() == 'submit'){
  95                  return 'nodisplay';
  96              } else {
  97                  return 'static';
  98              }
  99          } else {
 100              if ($this->getGroupType() == 'submit') {
 101                  return 'actionbuttons';
 102              }
 103              return 'fieldset';
 104          }
 105      }
 106  
 107      /**
 108       * Sets the grouped elements and hides label
 109       *
 110       * @param array $elements
 111       */
 112      function setElements($elements){
 113          parent::setElements($elements);
 114          foreach ($this->_elements as $element){
 115              if (method_exists($element, 'setHiddenLabel')){
 116                  $element->setHiddenLabel(true);
 117              }
 118          }
 119      }
 120  
 121      /**
 122       * Stores the form this element was added to
 123       * This object is later used by {@link MoodleQuickForm_group::createElement()}
 124       * @param null|MoodleQuickForm $mform
 125       */
 126      public function setMoodleForm($mform) {
 127          if ($mform && $mform instanceof MoodleQuickForm) {
 128              $this->_mform = $mform;
 129          }
 130      }
 131  
 132      /**
 133       * Called by HTML_QuickForm whenever form event is made on this element
 134       *
 135       * If this function is overridden and parent is not called the element must be responsible for
 136       * storing the MoodleQuickForm object, see {@link MoodleQuickForm_group::setMoodleForm()}
 137       *
 138       * @param     string $event Name of event
 139       * @param     mixed $arg event arguments
 140       * @param     mixed $caller calling object
 141       */
 142      public function onQuickFormEvent($event, $arg, &$caller) {
 143          $this->setMoodleForm($caller);
 144          return parent::onQuickFormEvent($event, $arg, $caller);
 145      }
 146  
 147      /**
 148       * Creates an element to add to the group
 149       * Expects the same arguments as MoodleQuickForm::createElement()
 150       */
 151      public function createFormElement() {
 152          if (!$this->_mform) {
 153              throw new coding_exception('You can not call createFormElement() on the group element that was not yet added to a form.');
 154          }
 155          return call_user_func_array([$this->_mform, 'createElement'], func_get_args());
 156      }
 157  
 158      /**
 159       * Return attributes suitable for passing to {@see createFormElement}, comprised of all group attributes without ID in
 160       * order to ensure uniqueness of that value within the group
 161       *
 162       * @return array
 163       */
 164      public function getAttributesForFormElement(): array {
 165          return array_diff_key((array) $this->getAttributes(), array_flip(['id']));
 166      }
 167  
 168      public function export_for_template(renderer_base $output) {
 169          global $OUTPUT;
 170  
 171          $context = $this->export_for_template_base($output);
 172  
 173          $this->_renderedfromtemplate = true;
 174  
 175          include_once('HTML/QuickForm/Renderer/Default.php');
 176  
 177          $elements = [];
 178          $name = $this->getName();
 179          $i = 0;
 180          foreach ($this->_elements as $key => $element) {
 181              $elementname = '';
 182              if ($this->_appendName) {
 183                  $elementname = $element->getName();
 184                  if (isset($elementname)) {
 185                      $element->setName($name . '['. (strlen($elementname) ? $elementname : $key) .']');
 186                  } else {
 187                      $element->setName($name);
 188                  }
 189              }
 190              $element->_generateId();
 191  
 192              $out = $OUTPUT->mform_element($element, false, false, '', true);
 193  
 194              if (empty($out)) {
 195                  $renderer = new HTML_QuickForm_Renderer_Default();
 196                  $renderer->setElementTemplate('{element}');
 197                  $element->accept($renderer);
 198                  $out = $renderer->toHtml();
 199              }
 200  
 201              // Replicates the separator logic from 'pear/HTML/QuickForm/Renderer/Default.php'.
 202              $separator = '';
 203              if ($i > 0) {
 204                  if (is_array($this->_separator)) {
 205                      $separator = $this->_separator[($i - 1) % count($this->_separator)];
 206                  } else if ($this->_separator === null) {
 207                      $separator = '&nbsp;';
 208                  } else {
 209                      $separator = (string) $this->_separator;
 210                  }
 211              }
 212  
 213              $elements[] = [
 214                  'separator' => $separator,
 215                  'html' => $out
 216              ];
 217  
 218              // Restore the element's name.
 219              if ($this->_appendName) {
 220                  $element->setName($elementname);
 221              }
 222  
 223              $i++;
 224          }
 225  
 226          $context['groupname'] = $name;
 227          $context['elements'] = $elements;
 228          return $context;
 229      }
 230  
 231      /**
 232       * Accepts a renderer
 233       *
 234       * @param object     An HTML_QuickForm_Renderer object
 235       * @param bool       Whether a group is required
 236       * @param string     An error message associated with a group
 237       * @access public
 238       * @return void
 239       */
 240      public function accept(&$renderer, $required = false, $error = null) {
 241          $this->_createElementsIfNotExist();
 242          $renderer->startGroup($this, $required, $error);
 243          if (!$this->_renderedfromtemplate) {
 244              // Backwards compatible path - only do this if we didn't render the sub-elements already.
 245              $name = $this->getName();
 246              foreach (array_keys($this->_elements) as $key) {
 247                  $element =& $this->_elements[$key];
 248                  $elementname = '';
 249                  if ($this->_appendName) {
 250                      $elementname = $element->getName();
 251                      if (isset($elementname)) {
 252                          $element->setName($name . '['. (strlen($elementname) ? $elementname : $key) .']');
 253                      } else {
 254                          $element->setName($name);
 255                      }
 256                  }
 257  
 258                  $required = !$element->isFrozen() && in_array($element->getName(), $this->_required);
 259  
 260                  $element->accept($renderer, $required);
 261  
 262                  // Restore the element's name.
 263                  if ($this->_appendName) {
 264                      $element->setName($elementname);
 265                  }
 266              }
 267          }
 268          $renderer->finishGroup($this);
 269      }
 270  
 271      /**
 272       * Calls the validateSubmitValue function for the containing elements and returns an error string as soon as it finds one.
 273       *
 274       * @param array $values Values of the containing elements.
 275       * @return string|null Validation error message or null.
 276       */
 277      public function validateSubmitValue($values) {
 278          foreach ($this->_elements as $element) {
 279              if (method_exists($element, 'validateSubmitValue')) {
 280                  $value = $values[$element->getName()] ?? null;
 281                  $result = $element->validateSubmitValue($value);
 282                  if (!empty($result) && is_string($result)) {
 283                      return $result;
 284                  }
 285              }
 286          }
 287      }
 288  }