[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace dokuwiki\Form;
   4  
   5  use dokuwiki\Extension\Event;
   6  
   7  /**
   8   * Class Form
   9   *
  10   * Represents the whole Form. This is what you work on, and add Elements to
  11   *
  12   * @package dokuwiki\Form
  13   */
  14  class Form extends Element
  15  {
  16      /**
  17       * @var array name value pairs for hidden values
  18       */
  19      protected $hidden = [];
  20  
  21      /**
  22       * @var Element[] the elements of the form
  23       */
  24      protected $elements = [];
  25  
  26      /**
  27       * Creates a new, empty form with some default attributes
  28       *
  29       * @param array $attributes
  30       * @param bool  $unsafe     if true, then the security token is ommited
  31       */
  32      public function __construct($attributes = [], $unsafe = false)
  33      {
  34          global $ID;
  35  
  36          parent::__construct('form', $attributes);
  37  
  38          // use the current URL as default action
  39          if (!$this->attr('action')) {
  40              $get = $_GET;
  41              if (isset($get['id'])) unset($get['id']);
  42              $self = wl($ID, $get, false, '&'); //attributes are escaped later
  43              $this->attr('action', $self);
  44          }
  45  
  46          // post is default
  47          if (!$this->attr('method')) {
  48              $this->attr('method', 'post');
  49          }
  50  
  51          // we like UTF-8
  52          if (!$this->attr('accept-charset')) {
  53              $this->attr('accept-charset', 'utf-8');
  54          }
  55  
  56          // add the security token by default
  57          if (!$unsafe) {
  58              $this->setHiddenField('sectok', getSecurityToken());
  59          }
  60  
  61          // identify this as a new form based form in HTML
  62          $this->addClass('doku_form');
  63      }
  64  
  65      /**
  66       * Sets a hidden field
  67       *
  68       * @param string $name
  69       * @param string $value
  70       * @return $this
  71       */
  72      public function setHiddenField($name, $value)
  73      {
  74          $this->hidden[$name] = $value;
  75          return $this;
  76      }
  77  
  78      #region element query function
  79  
  80      /**
  81       * Returns the numbers of elements in the form
  82       *
  83       * @return int
  84       */
  85      public function elementCount()
  86      {
  87          return count($this->elements);
  88      }
  89  
  90      /**
  91       * Get the position of the element in the form or false if it is not in the form
  92       *
  93       * Warning: This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates
  94       * to FALSE. Please read the section on Booleans for more information. Use the === operator for testing the
  95       * return value of this function.
  96       *
  97       * @param Element $element
  98       *
  99       * @return false|int
 100       */
 101      public function getElementPosition(Element $element)
 102      {
 103          return array_search($element, $this->elements, true);
 104      }
 105  
 106      /**
 107       * Returns a reference to the element at a position.
 108       * A position out-of-bounds will return either the
 109       * first (underflow) or last (overflow) element.
 110       *
 111       * @param int $pos
 112       * @return Element
 113       */
 114      public function getElementAt($pos)
 115      {
 116          if ($pos < 0) $pos = count($this->elements) + $pos;
 117          if ($pos < 0) $pos = 0;
 118          if ($pos >= count($this->elements)) $pos = count($this->elements) - 1;
 119          return $this->elements[$pos];
 120      }
 121  
 122      /**
 123       * Gets the position of the first of a type of element
 124       *
 125       * @param string $type Element type to look for.
 126       * @param int $offset search from this position onward
 127       * @return false|int position of element if found, otherwise false
 128       */
 129      public function findPositionByType($type, $offset = 0)
 130      {
 131          $len = $this->elementCount();
 132          for ($pos = $offset; $pos < $len; $pos++) {
 133              if ($this->elements[$pos]->getType() == $type) {
 134                  return $pos;
 135              }
 136          }
 137          return false;
 138      }
 139  
 140      /**
 141       * Gets the position of the first element matching the attribute
 142       *
 143       * @param string $name Name of the attribute
 144       * @param string $value Value the attribute should have
 145       * @param int $offset search from this position onward
 146       * @return false|int position of element if found, otherwise false
 147       */
 148      public function findPositionByAttribute($name, $value, $offset = 0)
 149      {
 150          $len = $this->elementCount();
 151          for ($pos = $offset; $pos < $len; $pos++) {
 152              if ($this->elements[$pos]->attr($name) == $value) {
 153                  return $pos;
 154              }
 155          }
 156          return false;
 157      }
 158  
 159      #endregion
 160  
 161      #region Element positioning functions
 162  
 163      /**
 164       * Adds or inserts an element to the form
 165       *
 166       * @param Element $element
 167       * @param int $pos 0-based position in the form, -1 for at the end
 168       * @return Element
 169       */
 170      public function addElement(Element $element, $pos = -1)
 171      {
 172          if (is_a($element, '\dokuwiki\Form\Form')) throw new \InvalidArgumentException(
 173              'You can\'t add a form to a form'
 174          );
 175          if ($pos < 0) {
 176              $this->elements[] = $element;
 177          } else {
 178              array_splice($this->elements, $pos, 0, [$element]);
 179          }
 180          return $element;
 181      }
 182  
 183      /**
 184       * Replaces an existing element with a new one
 185       *
 186       * @param Element $element the new element
 187       * @param int $pos 0-based position of the element to replace
 188       */
 189      public function replaceElement(Element $element, $pos)
 190      {
 191          if (is_a($element, '\dokuwiki\Form\Form')) throw new \InvalidArgumentException(
 192              'You can\'t add a form to a form'
 193          );
 194          array_splice($this->elements, $pos, 1, [$element]);
 195      }
 196  
 197      /**
 198       * Remove an element from the form completely
 199       *
 200       * @param int $pos 0-based position of the element to remove
 201       */
 202      public function removeElement($pos)
 203      {
 204          array_splice($this->elements, $pos, 1);
 205      }
 206  
 207      #endregion
 208  
 209      #region Element adding functions
 210  
 211      /**
 212       * Adds a text input field
 213       *
 214       * @param string $name
 215       * @param string $label
 216       * @param int $pos
 217       * @return InputElement
 218       */
 219      public function addTextInput($name, $label = '', $pos = -1)
 220      {
 221          return $this->addElement(new InputElement('text', $name, $label), $pos);
 222      }
 223  
 224      /**
 225       * Adds a password input field
 226       *
 227       * @param string $name
 228       * @param string $label
 229       * @param int $pos
 230       * @return InputElement
 231       */
 232      public function addPasswordInput($name, $label = '', $pos = -1)
 233      {
 234          return $this->addElement(new InputElement('password', $name, $label), $pos);
 235      }
 236  
 237      /**
 238       * Adds a radio button field
 239       *
 240       * @param string $name
 241       * @param string $label
 242       * @param int $pos
 243       * @return CheckableElement
 244       */
 245      public function addRadioButton($name, $label = '', $pos = -1)
 246      {
 247          return $this->addElement(new CheckableElement('radio', $name, $label), $pos);
 248      }
 249  
 250      /**
 251       * Adds a checkbox field
 252       *
 253       * @param string $name
 254       * @param string $label
 255       * @param int $pos
 256       * @return CheckableElement
 257       */
 258      public function addCheckbox($name, $label = '', $pos = -1)
 259      {
 260          return $this->addElement(new CheckableElement('checkbox', $name, $label), $pos);
 261      }
 262  
 263      /**
 264       * Adds a dropdown field
 265       *
 266       * @param string $name
 267       * @param array $options
 268       * @param string $label
 269       * @param int $pos
 270       * @return DropdownElement
 271       */
 272      public function addDropdown($name, $options, $label = '', $pos = -1)
 273      {
 274          return $this->addElement(new DropdownElement($name, $options, $label), $pos);
 275      }
 276  
 277      /**
 278       * Adds a textarea field
 279       *
 280       * @param string $name
 281       * @param string $label
 282       * @param int $pos
 283       * @return TextareaElement
 284       */
 285      public function addTextarea($name, $label = '', $pos = -1)
 286      {
 287          return $this->addElement(new TextareaElement($name, $label), $pos);
 288      }
 289  
 290      /**
 291       * Adds a simple button, escapes the content for you
 292       *
 293       * @param string $name
 294       * @param string $content
 295       * @param int $pos
 296       * @return Element
 297       */
 298      public function addButton($name, $content, $pos = -1)
 299      {
 300          return $this->addElement(new ButtonElement($name, hsc($content)), $pos);
 301      }
 302  
 303      /**
 304       * Adds a simple button, allows HTML for content
 305       *
 306       * @param string $name
 307       * @param string $html
 308       * @param int $pos
 309       * @return Element
 310       */
 311      public function addButtonHTML($name, $html, $pos = -1)
 312      {
 313          return $this->addElement(new ButtonElement($name, $html), $pos);
 314      }
 315  
 316      /**
 317       * Adds a label referencing another input element, escapes the label for you
 318       *
 319       * @param string $label
 320       * @param string $for
 321       * @param int $pos
 322       * @return Element
 323       */
 324      public function addLabel($label, $for = '', $pos = -1)
 325      {
 326          return $this->addLabelHTML(hsc($label), $for, $pos);
 327      }
 328  
 329      /**
 330       * Adds a label referencing another input element, allows HTML for content
 331       *
 332       * @param string $content
 333       * @param string|Element $for
 334       * @param int $pos
 335       * @return Element
 336       */
 337      public function addLabelHTML($content, $for = '', $pos = -1)
 338      {
 339          $element = new LabelElement($content);
 340  
 341          if (is_a($for, '\dokuwiki\Form\Element')) {
 342              /** @var Element $for */
 343              $for = $for->id();
 344          }
 345          $for = (string) $for;
 346          if ($for !== '') {
 347              $element->attr('for', $for);
 348          }
 349  
 350          return $this->addElement($element, $pos);
 351      }
 352  
 353      /**
 354       * Add fixed HTML to the form
 355       *
 356       * @param string $html
 357       * @param int $pos
 358       * @return HTMLElement
 359       */
 360      public function addHTML($html, $pos = -1)
 361      {
 362          return $this->addElement(new HTMLElement($html), $pos);
 363      }
 364  
 365      /**
 366       * Add a closed HTML tag to the form
 367       *
 368       * @param string $tag
 369       * @param int $pos
 370       * @return TagElement
 371       */
 372      public function addTag($tag, $pos = -1)
 373      {
 374          return $this->addElement(new TagElement($tag), $pos);
 375      }
 376  
 377      /**
 378       * Add an open HTML tag to the form
 379       *
 380       * Be sure to close it again!
 381       *
 382       * @param string $tag
 383       * @param int $pos
 384       * @return TagOpenElement
 385       */
 386      public function addTagOpen($tag, $pos = -1)
 387      {
 388          return $this->addElement(new TagOpenElement($tag), $pos);
 389      }
 390  
 391      /**
 392       * Add a closing HTML tag to the form
 393       *
 394       * Be sure it had been opened before
 395       *
 396       * @param string $tag
 397       * @param int $pos
 398       * @return TagCloseElement
 399       */
 400      public function addTagClose($tag, $pos = -1)
 401      {
 402          return $this->addElement(new TagCloseElement($tag), $pos);
 403      }
 404  
 405      /**
 406       * Open a Fieldset
 407       *
 408       * @param string $legend
 409       * @param int $pos
 410       * @return FieldsetOpenElement
 411       */
 412      public function addFieldsetOpen($legend = '', $pos = -1)
 413      {
 414          return $this->addElement(new FieldsetOpenElement($legend), $pos);
 415      }
 416  
 417      /**
 418       * Close a fieldset
 419       *
 420       * @param int $pos
 421       * @return TagCloseElement
 422       */
 423      public function addFieldsetClose($pos = -1)
 424      {
 425          return $this->addElement(new FieldsetCloseElement(), $pos);
 426      }
 427  
 428      #endregion
 429  
 430      /**
 431       * Adjust the elements so that fieldset open and closes are matching
 432       */
 433      protected function balanceFieldsets()
 434      {
 435          $lastclose = 0;
 436          $isopen = false;
 437          $len = count($this->elements);
 438  
 439          for ($pos = 0; $pos < $len; $pos++) {
 440              $type = $this->elements[$pos]->getType();
 441              if ($type == 'fieldsetopen') {
 442                  if ($isopen) {
 443                      //close previous fieldset
 444                      $this->addFieldsetClose($pos);
 445                      $lastclose = $pos + 1;
 446                      $pos++;
 447                      $len++;
 448                  }
 449                  $isopen = true;
 450              } elseif ($type == 'fieldsetclose') {
 451                  if (!$isopen) {
 452                      // make sure there was a fieldsetopen
 453                      // either right after the last close or at the begining
 454                      $this->addFieldsetOpen('', $lastclose);
 455                      $len++;
 456                      $pos++;
 457                  }
 458                  $lastclose = $pos;
 459                  $isopen = false;
 460              }
 461          }
 462  
 463          // close open fieldset at the end
 464          if ($isopen) {
 465              $this->addFieldsetClose();
 466          }
 467      }
 468  
 469      /**
 470       * The HTML representation of the whole form
 471       *
 472       * @param string $eventName  (optional) name of the event: FORM_{$name}_OUTPUT
 473       * @return string
 474       */
 475      public function toHTML($eventName = null)
 476      {
 477          $this->balanceFieldsets();
 478  
 479          // trigger event to provide an opportunity to modify this form
 480          if (isset($eventName)) {
 481              $eventName = 'FORM_' . strtoupper($eventName) . '_OUTPUT';
 482              Event::createAndTrigger($eventName, $this, null, false);
 483          }
 484  
 485          $html = '<form ' . buildAttributes($this->attrs()) . '>';
 486  
 487          foreach ($this->hidden as $name => $value) {
 488              $html .= '<input type="hidden" name="' . $name . '" value="' . formText($value) . '" />';
 489          }
 490  
 491          foreach ($this->elements as $element) {
 492              $html .= $element->toHTML();
 493          }
 494  
 495          $html .= '</form>';
 496  
 497          return $html;
 498      }
 499  }