[ Index ]

PHP Cross Reference of DokuWiki

title

Body

[close]

/inc/ -> form.php (source)

   1  <?php
   2  /**
   3   * DokuWiki XHTML Form
   4   *
   5   * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
   6   * @author     Tom N Harris <tnharris@whoopdedo.org>
   7   */
   8  
   9  // phpcs:disable Squiz.Classes.ValidClassName.NotCamelCaps
  10  // phpcs:disable PSR2.Classes.PropertyDeclaration.Underscore
  11  
  12  
  13  /**
  14   * Class for creating simple HTML forms.
  15   *
  16   * The forms is built from a list of pseudo-tags (arrays with expected keys).
  17   * Every pseudo-tag must have the key '_elem' set to the name of the element.
  18   * When printed, the form class calls functions named 'form_$type' for each
  19   * element it contains.
  20   *
  21   * Standard practice is for non-attribute keys in a pseudo-element to start
  22   * with '_'. Other keys are HTML attributes that will be included in the element
  23   * tag. That way, the element output functions can pass the pseudo-element
  24   * directly to buildAttributes.
  25   *
  26   * See the form_make* functions later in this file.
  27   *
  28   * Please note that even though this class is technically deprecated (use dokuwiki\Form instead),
  29   * it is still widely used in the core and the related form events. Until those have been rewritten,
  30   * this will continue to be used
  31   *
  32   * @deprecated 2019-07-14
  33   * @author Tom N Harris <tnharris@whoopdedo.org>
  34   */
  35  class Doku_Form
  36  {
  37      // Form id attribute
  38      public $params = array();
  39  
  40      // Draw a border around form fields.
  41      // Adds <fieldset></fieldset> around the elements
  42      public $_infieldset = false;
  43  
  44      // Hidden form fields.
  45      public $_hidden = array();
  46  
  47      // Array of pseudo-tags
  48      public $_content = array();
  49  
  50      /**
  51       * Constructor
  52       *
  53       * Sets parameters and autoadds a security token. The old calling convention
  54       * with up to four parameters is deprecated, instead the first parameter
  55       * should be an array with parameters.
  56       *
  57       * @param mixed       $params  Parameters for the HTML form element; Using the deprecated
  58       *                             calling convention this is the ID attribute of the form
  59       * @param bool|string $action  (optional, deprecated) submit URL, defaults to current page
  60       * @param bool|string $method  (optional, deprecated) 'POST' or 'GET', default is POST
  61       * @param bool|string $enctype (optional, deprecated) Encoding type of the data
  62       *
  63       * @author  Tom N Harris <tnharris@whoopdedo.org>
  64       */
  65      public function __construct($params, $action=false, $method=false, $enctype=false)
  66      {
  67          if (!is_array($params)) {
  68              $this->params = array('id' => $params);
  69              if ($action !== false) $this->params['action'] = $action;
  70              if ($method !== false) $this->params['method'] = strtolower($method);
  71              if ($enctype !== false) $this->params['enctype'] = $enctype;
  72          } else {
  73              $this->params = $params;
  74          }
  75  
  76          if (!isset($this->params['method'])) {
  77              $this->params['method'] = 'post';
  78          } else {
  79              $this->params['method'] = strtolower($this->params['method']);
  80          }
  81  
  82          if (!isset($this->params['action'])) {
  83              $this->params['action'] = '';
  84          }
  85  
  86          $this->addHidden('sectok', getSecurityToken());
  87      }
  88  
  89      /**
  90       * startFieldset
  91       *
  92       * Add <fieldset></fieldset> tags around fields.
  93       * Usually results in a border drawn around the form.
  94       *
  95       * @param   string  $legend Label that will be printed with the border.
  96       *
  97       * @author  Tom N Harris <tnharris@whoopdedo.org>
  98       */
  99      public function startFieldset($legend)
 100      {
 101          if ($this->_infieldset) {
 102              $this->addElement(array('_elem'=>'closefieldset'));
 103          }
 104          $this->addElement(array('_elem'=>'openfieldset', '_legend'=>$legend));
 105          $this->_infieldset = true;
 106      }
 107  
 108      /**
 109       * endFieldset
 110       *
 111       * @author  Tom N Harris <tnharris@whoopdedo.org>
 112       */
 113      public function endFieldset()
 114      {
 115          if ($this->_infieldset) {
 116              $this->addElement(array('_elem'=>'closefieldset'));
 117          }
 118          $this->_infieldset = false;
 119      }
 120  
 121      /**
 122       * addHidden
 123       *
 124       * Adds a name/value pair as a hidden field.
 125       * The value of the field (but not the name) will be passed to
 126       * formText() before printing.
 127       *
 128       * @param   string  $name   Field name.
 129       * @param   string  $value  Field value. If null, remove a previously added field.
 130       *
 131       * @author  Tom N Harris <tnharris@whoopdedo.org>
 132       */
 133      public function addHidden($name, $value)
 134      {
 135          if (is_null($value))
 136              unset($this->_hidden[$name]);
 137          else
 138              $this->_hidden[$name] = $value;
 139      }
 140  
 141      /**
 142       * addElement
 143       *
 144       * Appends a content element to the form.
 145       * The element can be either a pseudo-tag or string.
 146       * If string, it is printed without escaping special chars.   *
 147       *
 148       * @param   string|array  $elem   Pseudo-tag or string to add to the form.
 149       *
 150       * @author  Tom N Harris <tnharris@whoopdedo.org>
 151       */
 152      public function addElement($elem)
 153      {
 154          $this->_content[] = $elem;
 155      }
 156  
 157      /**
 158       * insertElement
 159       *
 160       * Inserts a content element at a position.
 161       *
 162       * @param   string       $pos  0-based index where the element will be inserted.
 163       * @param   string|array $elem Pseudo-tag or string to add to the form.
 164       *
 165       * @author  Tom N Harris <tnharris@whoopdedo.org>
 166       */
 167      public function insertElement($pos, $elem)
 168      {
 169          array_splice($this->_content, $pos, 0, array($elem));
 170      }
 171  
 172      /**
 173       * replaceElement
 174       *
 175       * Replace with NULL to remove an element.
 176       *
 177       * @param   int          $pos  0-based index the element will be placed at.
 178       * @param   string|array $elem Pseudo-tag or string to add to the form.
 179       *
 180       * @author  Tom N Harris <tnharris@whoopdedo.org>
 181       */
 182      public function replaceElement($pos, $elem)
 183      {
 184          $rep = array();
 185          if (!is_null($elem)) $rep[] = $elem;
 186          array_splice($this->_content, $pos, 1, $rep);
 187      }
 188  
 189      /**
 190       * findElementByType
 191       *
 192       * Gets the position of the first of a type of element.
 193       *
 194       * @param   string  $type   Element type to look for.
 195       * @return  int|false     position of element if found, otherwise false
 196       *
 197       * @author  Tom N Harris <tnharris@whoopdedo.org>
 198       */
 199      public function findElementByType($type)
 200      {
 201          foreach ($this->_content as $pos => $elem) {
 202              if (is_array($elem) && $elem['_elem'] == $type)
 203                  return $pos;
 204          }
 205          return false;
 206      }
 207  
 208      /**
 209       * findElementById
 210       *
 211       * Gets the position of the element with an ID attribute.
 212       *
 213       * @param   string  $id     ID of the element to find.
 214       * @return  int|false     position of element if found, otherwise false
 215       *
 216       * @author  Tom N Harris <tnharris@whoopdedo.org>
 217       */
 218      public function findElementById($id)
 219      {
 220          foreach ($this->_content as $pos => $elem) {
 221              if (is_array($elem) && isset($elem['id']) && $elem['id'] == $id)
 222                  return $pos;
 223          }
 224          return false;
 225      }
 226  
 227      /**
 228       * findElementByAttribute
 229       *
 230       * Gets the position of the first element with a matching attribute value.
 231       *
 232       * @param   string  $name   Attribute name.
 233       * @param   string  $value  Attribute value.
 234       * @return  int|false     position of element if found, otherwise false
 235       *
 236       * @author  Tom N Harris <tnharris@whoopdedo.org>
 237       */
 238      public function findElementByAttribute($name, $value)
 239      {
 240          foreach ($this->_content as $pos => $elem) {
 241              if (is_array($elem) && isset($elem[$name]) && $elem[$name] == $value)
 242                  return $pos;
 243          }
 244          return false;
 245      }
 246  
 247      /**
 248       * getElementAt
 249       *
 250       * Returns a reference to the element at a position.
 251       * A position out-of-bounds will return either the
 252       * first (underflow) or last (overflow) element.
 253       *
 254       * @param   int     $pos    0-based index
 255       * @return  array reference  pseudo-element
 256       *
 257       * @author  Tom N Harris <tnharris@whoopdedo.org>
 258       */
 259      public function &getElementAt($pos)
 260      {
 261          if ($pos < 0) $pos = count($this->_content) + $pos;
 262          if ($pos < 0) $pos = 0;
 263          if ($pos >= count($this->_content)) $pos = count($this->_content) - 1;
 264          return $this->_content[$pos];
 265      }
 266  
 267      /**
 268       * Return the assembled HTML for the form.
 269       *
 270       * Each element in the form will be passed to a function named
 271       * 'form_$type'. The function should return the HTML to be printed.
 272       *
 273       * @author  Tom N Harris <tnharris@whoopdedo.org>
 274       *
 275       * @return string html of the form
 276       */
 277      public function getForm()
 278      {
 279          global $lang;
 280          $form = '';
 281          $this->params['accept-charset'] = $lang['encoding'];
 282          $form .= '<form '. buildAttributes($this->params,false) .'><div class="no">'. DOKU_LF;
 283          if (!empty($this->_hidden)) {
 284              foreach ($this->_hidden as $name => $value)
 285                  $form .= form_hidden(array('name'=>$name, 'value'=>$value));
 286          }
 287          foreach ($this->_content as $element) {
 288              if (is_array($element)) {
 289                  $elem_type = $element['_elem'];
 290                  if (function_exists('form_'.$elem_type)) {
 291                      $form .= call_user_func('form_'.$elem_type, $element).DOKU_LF;
 292                  }
 293              } else {
 294                  $form .= $element;
 295              }
 296          }
 297          if ($this->_infieldset) $form .= form_closefieldset().DOKU_LF;
 298          $form .= '</div></form>'.DOKU_LF;
 299  
 300          return $form;
 301      }
 302  
 303      /**
 304       * Print the assembled form
 305       *
 306       * wraps around getForm()
 307       */
 308      public function printForm()
 309      {
 310          echo $this->getForm();
 311      }
 312  
 313      /**
 314       * Add a radio set
 315       *
 316       * This function adds a set of radio buttons to the form. If $_POST[$name]
 317       * is set, this radio is preselected, else the first radio button.
 318       *
 319       * @param string    $name    The HTML field name
 320       * @param array     $entries An array of entries $value => $caption
 321       *
 322       * @author Adrian Lang <lang@cosmocode.de>
 323       */
 324  
 325      public function addRadioSet($name, $entries)
 326      {
 327          global $INPUT;
 328          $value = (array_key_exists($INPUT->post->str($name), $entries)) ?
 329                   $INPUT->str($name) : key($entries);
 330          foreach($entries as $val => $cap) {
 331              $data = ($value === $val) ? array('checked' => 'checked') : array();
 332              $this->addElement(form_makeRadioField($name, $val, $cap, '', '', $data));
 333          }
 334      }
 335  
 336  }
 337  
 338  /**
 339   * form_makeTag
 340   *
 341   * Create a form element for a non-specific empty tag.
 342   *
 343   * @param   string  $tag    Tag name.
 344   * @param   array   $attrs  Optional attributes.
 345   * @return  array   pseudo-tag
 346   *
 347   * @author  Tom N Harris <tnharris@whoopdedo.org>
 348   */
 349  function form_makeTag($tag, $attrs=array()) {
 350      $elem = array('_elem'=>'tag', '_tag'=>$tag);
 351      return array_merge($elem, $attrs);
 352  }
 353  
 354  /**
 355   * form_makeOpenTag
 356   *
 357   * Create a form element for a non-specific opening tag.
 358   * Remember to put a matching close tag after this as well.
 359   *
 360   * @param   string  $tag    Tag name.
 361   * @param   array   $attrs  Optional attributes.
 362   * @return  array   pseudo-tag
 363   *
 364   * @author  Tom N Harris <tnharris@whoopdedo.org>
 365   */
 366  function form_makeOpenTag($tag, $attrs=array()) {
 367      $elem = array('_elem'=>'opentag', '_tag'=>$tag);
 368      return array_merge($elem, $attrs);
 369  }
 370  
 371  /**
 372   * form_makeCloseTag
 373   *
 374   * Create a form element for a non-specific closing tag.
 375   * Careless use of this will result in invalid XHTML.
 376   *
 377   * @param   string  $tag    Tag name.
 378   * @return  array   pseudo-tag
 379   *
 380   * @author  Tom N Harris <tnharris@whoopdedo.org>
 381   */
 382  function form_makeCloseTag($tag) {
 383      return array('_elem'=>'closetag', '_tag'=>$tag);
 384  }
 385  
 386  /**
 387   * form_makeWikiText
 388   *
 389   * Create a form element for a textarea containing wiki text.
 390   * Only one wikitext element is allowed on a page. It will have
 391   * a name of 'wikitext' and id 'wiki__text'. The text will
 392   * be passed to formText() before printing.
 393   *
 394   * @param   string  $text   Text to fill the field with.
 395   * @param   array   $attrs  Optional attributes.
 396   * @return  array   pseudo-tag
 397   *
 398   * @author  Tom N Harris <tnharris@whoopdedo.org>
 399   */
 400  function form_makeWikiText($text, $attrs=array()) {
 401      $elem = array('_elem'=>'wikitext', '_text'=>$text,
 402                          'class'=>'edit', 'cols'=>'80', 'rows'=>'10');
 403      return array_merge($elem, $attrs);
 404  }
 405  
 406  /**
 407   * form_makeButton
 408   *
 409   * Create a form element for an action button.
 410   * A title will automatically be generated using the value and
 411   * accesskey attributes, unless you provide one.
 412   *
 413   * @param   string  $type   Type attribute. 'submit' or 'cancel'
 414   * @param   string  $act    Wiki action of the button, will be used as the do= parameter
 415   * @param   string  $value  (optional) Displayed label. Uses $act if not provided.
 416   * @param   array   $attrs  Optional attributes.
 417   * @return  array   pseudo-tag
 418   *
 419   * @author  Tom N Harris <tnharris@whoopdedo.org>
 420   */
 421  function form_makeButton($type, $act, $value='', $attrs=array()) {
 422      if ($value == '') $value = $act;
 423      $elem = array('_elem'=>'button', 'type'=>$type, '_action'=>$act,
 424                          'value'=>$value);
 425      if (!empty($attrs['accesskey']) && empty($attrs['title'])) {
 426          $attrs['title'] = $value .' ['. strtoupper($attrs['accesskey']) .']';
 427      }
 428      return array_merge($elem, $attrs);
 429  }
 430  
 431  /**
 432   * form_makeField
 433   *
 434   * Create a form element for a labelled input element.
 435   * The label text will be printed before the input.
 436   *
 437   * @param   string  $type   Type attribute of input.
 438   * @param   string  $name   Name attribute of the input.
 439   * @param   string  $value  (optional) Default value.
 440   * @param   string  $class  Class attribute of the label. If this is 'block',
 441   *                          then a line break will be added after the field.
 442   * @param   string  $label  Label that will be printed before the input.
 443   * @param   string  $id     ID attribute of the input. If set, the label will
 444   *                          reference it with a 'for' attribute.
 445   * @param   array   $attrs  Optional attributes.
 446   * @return  array   pseudo-tag
 447   *
 448   * @author  Tom N Harris <tnharris@whoopdedo.org>
 449   */
 450  function form_makeField($type, $name, $value='', $label=null, $id='', $class='', $attrs=array()) {
 451      if (is_null($label)) $label = $name;
 452      $elem = array('_elem'=>'field', '_text'=>$label, '_class'=>$class,
 453                          'type'=>$type, 'id'=>$id, 'name'=>$name, 'value'=>$value);
 454      return array_merge($elem, $attrs);
 455  }
 456  
 457  /**
 458   * form_makeFieldRight
 459   *
 460   * Create a form element for a labelled input element.
 461   * The label text will be printed after the input.
 462   *
 463   * @see     form_makeField
 464   * @author  Tom N Harris <tnharris@whoopdedo.org>
 465   *
 466   * @param string $type
 467   * @param string $name
 468   * @param string $value
 469   * @param null|string $label
 470   * @param string $id
 471   * @param string $class
 472   * @param array $attrs
 473   *
 474   * @return array
 475   */
 476  function form_makeFieldRight($type, $name, $value='', $label=null, $id='', $class='', $attrs=array()) {
 477      if (is_null($label)) $label = $name;
 478      $elem = array('_elem'=>'fieldright', '_text'=>$label, '_class'=>$class,
 479                          'type'=>$type, 'id'=>$id, 'name'=>$name, 'value'=>$value);
 480      return array_merge($elem, $attrs);
 481  }
 482  
 483  /**
 484   * form_makeTextField
 485   *
 486   * Create a form element for a text input element with label.
 487   *
 488   * @see     form_makeField
 489   * @author  Tom N Harris <tnharris@whoopdedo.org>
 490   *
 491   * @param string $name
 492   * @param string $value
 493   * @param null|string $label
 494   * @param string $id
 495   * @param string $class
 496   * @param array $attrs
 497   *
 498   * @return array
 499   */
 500  function form_makeTextField($name, $value='', $label=null, $id='', $class='', $attrs=array()) {
 501      if (is_null($label)) $label = $name;
 502      $elem = array('_elem'=>'textfield', '_text'=>$label, '_class'=>$class,
 503                          'id'=>$id, 'name'=>$name, 'value'=>$value, 'class'=>'edit');
 504      return array_merge($elem, $attrs);
 505  }
 506  
 507  /**
 508   * form_makePasswordField
 509   *
 510   * Create a form element for a password input element with label.
 511   * Password elements have no default value, for obvious reasons.
 512   *
 513   * @see     form_makeField
 514   * @author  Tom N Harris <tnharris@whoopdedo.org>
 515   *
 516   * @param string $name
 517   * @param null|string $label
 518   * @param string $id
 519   * @param string $class
 520   * @param array $attrs
 521   *
 522   * @return array
 523   */
 524  function form_makePasswordField($name, $label=null, $id='', $class='', $attrs=array()) {
 525      if (is_null($label)) $label = $name;
 526      $elem = array('_elem'=>'passwordfield', '_text'=>$label, '_class'=>$class,
 527                          'id'=>$id, 'name'=>$name, 'class'=>'edit');
 528      return array_merge($elem, $attrs);
 529  }
 530  
 531  /**
 532   * form_makeFileField
 533   *
 534   * Create a form element for a file input element with label
 535   *
 536   * @see     form_makeField
 537   * @author  Michael Klier <chi@chimeric.de>
 538   *
 539   * @param string $name
 540   * @param null|string $label
 541   * @param string $id
 542   * @param string $class
 543   * @param array $attrs
 544   *
 545   * @return array
 546   */
 547  function form_makeFileField($name, $label=null, $id='', $class='', $attrs=array()) {
 548      if (is_null($label)) $label = $name;
 549      $elem = array('_elem'=>'filefield', '_text'=>$label, '_class'=>$class,
 550                          'id'=>$id, 'name'=>$name, 'class'=>'edit');
 551      return array_merge($elem, $attrs);
 552  }
 553  
 554  /**
 555   * form_makeCheckboxField
 556   *
 557   * Create a form element for a checkbox input element with label.
 558   * If $value is an array, a hidden field with the same name and the value
 559   * $value[1] is constructed as well.
 560   *
 561   * @see     form_makeFieldRight
 562   * @author  Tom N Harris <tnharris@whoopdedo.org>
 563   *
 564   * @param string $name
 565   * @param string $value
 566   * @param null|string $label
 567   * @param string $id
 568   * @param string $class
 569   * @param array $attrs
 570   *
 571   * @return array
 572   */
 573  function form_makeCheckboxField($name, $value='1', $label=null, $id='', $class='', $attrs=array()) {
 574      if (is_null($label)) $label = $name;
 575      if (is_null($value) || $value=='') $value='0';
 576      $elem = array('_elem'=>'checkboxfield', '_text'=>$label, '_class'=>$class,
 577                          'id'=>$id, 'name'=>$name, 'value'=>$value);
 578      return array_merge($elem, $attrs);
 579  }
 580  
 581  /**
 582   * form_makeRadioField
 583   *
 584   * Create a form element for a radio button input element with label.
 585   *
 586   * @see     form_makeFieldRight
 587   * @author  Tom N Harris <tnharris@whoopdedo.org>
 588   *
 589   * @param string $name
 590   * @param string $value
 591   * @param null|string $label
 592   * @param string $id
 593   * @param string $class
 594   * @param array $attrs
 595   *
 596   * @return array
 597   */
 598  function form_makeRadioField($name, $value='1', $label=null, $id='', $class='', $attrs=array()) {
 599      if (is_null($label)) $label = $name;
 600      if (is_null($value) || $value=='') $value='0';
 601      $elem = array('_elem'=>'radiofield', '_text'=>$label, '_class'=>$class,
 602                          'id'=>$id, 'name'=>$name, 'value'=>$value);
 603      return array_merge($elem, $attrs);
 604  }
 605  
 606  /**
 607   * form_makeMenuField
 608   *
 609   * Create a form element for a drop-down menu with label.
 610   * The list of values can be strings, arrays of (value,text),
 611   * or an associative array with the values as keys and labels as values.
 612   * An item is selected by supplying its value or integer index.
 613   * If the list of values is an associative array, the selected item must be
 614   * a string.
 615   *
 616   * @author  Tom N Harris <tnharris@whoopdedo.org>
 617   *
 618   * @param string           $name     Name attribute of the input.
 619   * @param string[]|array[] $values   The list of values can be strings, arrays of (value,text),
 620   *                                   or an associative array with the values as keys and labels as values.
 621   * @param string|int       $selected default selected value, string or index number
 622   * @param string           $class    Class attribute of the label. If this is 'block',
 623   *                                   then a line break will be added after the field.
 624   * @param string           $label    Label that will be printed before the input.
 625   * @param string           $id       ID attribute of the input. If set, the label will
 626   *                                   reference it with a 'for' attribute.
 627   * @param array            $attrs    Optional attributes.
 628   * @return array   pseudo-tag
 629   */
 630  function form_makeMenuField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) {
 631      if (is_null($label)) $label = $name;
 632      $options = array();
 633      reset($values);
 634      // FIXME: php doesn't know the difference between a string and an integer
 635      if (is_string(key($values))) {
 636          foreach ($values as $val => $text) {
 637              $options[] = array($val, $text, (!is_null($selected) && $val==$selected));
 638          }
 639      } else {
 640          if (is_integer($selected)) $selected = $values[$selected];
 641          foreach ($values as $val) {
 642              if (is_array($val))
 643                  @list($val, $text) = $val;
 644              else
 645                  $text = null;
 646              $options[] = array($val, $text, $val===$selected);
 647          }
 648      }
 649      $elem = array('_elem'=>'menufield', '_options'=>$options, '_text'=>$label, '_class'=>$class,
 650                          'id'=>$id, 'name'=>$name);
 651      return array_merge($elem, $attrs);
 652  }
 653  
 654  /**
 655   * form_makeListboxField
 656   *
 657   * Create a form element for a list box with label.
 658   * The list of values can be strings, arrays of (value,text),
 659   * or an associative array with the values as keys and labels as values.
 660   * Items are selected by supplying its value or an array of values.
 661   *
 662   * @author  Tom N Harris <tnharris@whoopdedo.org>
 663   *
 664   * @param string           $name     Name attribute of the input.
 665   * @param string[]|array[] $values   The list of values can be strings, arrays of (value,text),
 666   *                                   or an associative array with the values as keys and labels as values.
 667   * @param array|string     $selected value or array of values of the items that need to be selected
 668   * @param string           $class    Class attribute of the label. If this is 'block',
 669   *                                   then a line break will be added after the field.
 670   * @param string           $label    Label that will be printed before the input.
 671   * @param string           $id       ID attribute of the input. If set, the label will
 672   *                                   reference it with a 'for' attribute.
 673   * @param array            $attrs    Optional attributes.
 674   * @return array   pseudo-tag
 675   */
 676  function form_makeListboxField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) {
 677      if (is_null($label)) $label = $name;
 678      $options = array();
 679      reset($values);
 680      if (is_null($selected) || $selected == '') {
 681          $selected = array();
 682      } elseif (!is_array($selected)) {
 683          $selected = array($selected);
 684      }
 685      // FIXME: php doesn't know the difference between a string and an integer
 686      if (is_string(key($values))) {
 687          foreach ($values as $val => $text) {
 688              $options[] = array($val, $text, in_array($val,$selected));
 689          }
 690      } else {
 691          foreach ($values as $val) {
 692              $disabled = false;
 693              if (is_array($val)) {
 694                  @list($val, $text, $disabled) = $val;
 695              } else {
 696                  $text = null;
 697              }
 698              $options[] = array($val, $text, in_array($val, $selected), $disabled);
 699          }
 700      }
 701      $elem = array('_elem'=>'listboxfield', '_options'=>$options, '_text'=>$label, '_class'=>$class,
 702                          'id'=>$id, 'name'=>$name);
 703      return array_merge($elem, $attrs);
 704  }
 705  
 706  /**
 707   * form_tag
 708   *
 709   * Print the HTML for a generic empty tag.
 710   * Requires '_tag' key with name of the tag.
 711   * Attributes are passed to buildAttributes()
 712   *
 713   * @author  Tom N Harris <tnharris@whoopdedo.org>
 714   *
 715   * @param array $attrs attributes
 716   * @return string html of tag
 717   */
 718  function form_tag($attrs) {
 719      return '<'.$attrs['_tag'].' '. buildAttributes($attrs,true) .'/>';
 720  }
 721  
 722  /**
 723   * form_opentag
 724   *
 725   * Print the HTML for a generic opening tag.
 726   * Requires '_tag' key with name of the tag.
 727   * Attributes are passed to buildAttributes()
 728   *
 729   * @author  Tom N Harris <tnharris@whoopdedo.org>
 730   *
 731   * @param array $attrs attributes
 732   * @return string html of tag
 733   */
 734  function form_opentag($attrs) {
 735      return '<'.$attrs['_tag'].' '. buildAttributes($attrs,true) .'>';
 736  }
 737  
 738  /**
 739   * form_closetag
 740   *
 741   * Print the HTML for a generic closing tag.
 742   * Requires '_tag' key with name of the tag.
 743   * There are no attributes.
 744   *
 745   * @author  Tom N Harris <tnharris@whoopdedo.org>
 746   *
 747   * @param array $attrs attributes
 748   * @return string html of tag
 749   */
 750  function form_closetag($attrs) {
 751      return '</'.$attrs['_tag'].'>';
 752  }
 753  
 754  /**
 755   * form_openfieldset
 756   *
 757   * Print the HTML for an opening fieldset tag.
 758   * Uses the '_legend' key.
 759   * Attributes are passed to buildAttributes()
 760   *
 761   * @author  Tom N Harris <tnharris@whoopdedo.org>
 762   *
 763   * @param array $attrs attributes
 764   * @return string html
 765   */
 766  function form_openfieldset($attrs) {
 767      $s = '<fieldset '. buildAttributes($attrs,true) .'>';
 768      if (!is_null($attrs['_legend'])) $s .= '<legend>'.$attrs['_legend'].'</legend>';
 769      return $s;
 770  }
 771  
 772  /**
 773   * form_closefieldset
 774   *
 775   * Print the HTML for a closing fieldset tag.
 776   * There are no attributes.
 777   *
 778   * @author  Tom N Harris <tnharris@whoopdedo.org>
 779   *
 780   * @return string html
 781   */
 782  function form_closefieldset() {
 783      return '</fieldset>';
 784  }
 785  
 786  /**
 787   * form_hidden
 788   *
 789   * Print the HTML for a hidden input element.
 790   * Uses only 'name' and 'value' attributes.
 791   * Value is passed to formText()
 792   *
 793   * @author  Tom N Harris <tnharris@whoopdedo.org>
 794   *
 795   * @param array $attrs attributes
 796   * @return string html
 797   */
 798  function form_hidden($attrs) {
 799      return '<input type="hidden" name="'.$attrs['name'].'" value="'. formText($attrs['value']) .'" />';
 800  }
 801  
 802  /**
 803   * form_wikitext
 804   *
 805   * Print the HTML for the wiki textarea.
 806   * Requires '_text' with default text of the field.
 807   * Text will be passed to formText(), attributes to buildAttributes()
 808   *
 809   * @author  Tom N Harris <tnharris@whoopdedo.org>
 810   *
 811   * @param array $attrs attributes
 812   * @return string html
 813   */
 814  function form_wikitext($attrs) {
 815      // mandatory attributes
 816      unset($attrs['name']);
 817      unset($attrs['id']);
 818      return '<textarea name="wikitext" id="wiki__text" dir="auto" '
 819                  . buildAttributes($attrs,true).'>'.DOKU_LF
 820                  . formText($attrs['_text'])
 821                  .'</textarea>';
 822  }
 823  
 824  /**
 825   * form_button
 826   *
 827   * Print the HTML for a form button.
 828   * If '_action' is set, the button name will be "do[_action]".
 829   * Other attributes are passed to buildAttributes()
 830   *
 831   * @author  Tom N Harris <tnharris@whoopdedo.org>
 832   *
 833   * @param array $attrs attributes
 834   * @return string html
 835   */
 836  function form_button($attrs) {
 837      $p = (!empty($attrs['_action'])) ? 'name="do['.$attrs['_action'].']" ' : '';
 838      $value = $attrs['value'];
 839      unset($attrs['value']);
 840      return '<button '.$p. buildAttributes($attrs,true) .'>'.$value.'</button>';
 841  }
 842  
 843  /**
 844   * form_field
 845   *
 846   * Print the HTML for a form input field.
 847   *   _class : class attribute used on the label tag
 848   *   _text  : Text to display before the input. Not escaped.
 849   * Other attributes are passed to buildAttributes() for the input tag.
 850   *
 851   * @author  Tom N Harris <tnharris@whoopdedo.org>
 852   *
 853   * @param array $attrs attributes
 854   * @return string html
 855   */
 856  function form_field($attrs) {
 857      $s = '<label';
 858      if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
 859      if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
 860      $s .= '><span>'.$attrs['_text'].'</span>';
 861      $s .= ' <input '. buildAttributes($attrs,true) .' /></label>';
 862      if (preg_match('/(^| )block($| )/', $attrs['_class']))
 863          $s .= '<br />';
 864      return $s;
 865  }
 866  
 867  /**
 868   * form_fieldright
 869   *
 870   * Print the HTML for a form input field. (right-aligned)
 871   *   _class : class attribute used on the label tag
 872   *   _text  : Text to display after the input. Not escaped.
 873   * Other attributes are passed to buildAttributes() for the input tag.
 874   *
 875   * @author  Tom N Harris <tnharris@whoopdedo.org>
 876   *
 877   * @param array $attrs attributes
 878   * @return string html
 879   */
 880  function form_fieldright($attrs) {
 881      $s = '<label';
 882      if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
 883      if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
 884      $s .= '><input '. buildAttributes($attrs,true) .' />';
 885      $s .= ' <span>'.$attrs['_text'].'</span></label>';
 886      if (preg_match('/(^| )block($| )/', $attrs['_class']))
 887          $s .= '<br />';
 888      return $s;
 889  }
 890  
 891  /**
 892   * form_textfield
 893   *
 894   * Print the HTML for a text input field.
 895   *   _class : class attribute used on the label tag
 896   *   _text  : Text to display before the input. Not escaped.
 897   * Other attributes are passed to buildAttributes() for the input tag.
 898   *
 899   * @author  Tom N Harris <tnharris@whoopdedo.org>
 900   *
 901   * @param array $attrs attributes
 902   * @return string html
 903   */
 904  function form_textfield($attrs) {
 905      // mandatory attributes
 906      unset($attrs['type']);
 907      $s = '<label';
 908      if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
 909      if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
 910      $s .= '><span>'.$attrs['_text'].'</span> ';
 911      $s .= '<input type="text" '. buildAttributes($attrs,true) .' /></label>';
 912      if (preg_match('/(^| )block($| )/', $attrs['_class']))
 913          $s .= '<br />';
 914      return $s;
 915  }
 916  
 917  /**
 918   * form_passwordfield
 919   *
 920   * Print the HTML for a password input field.
 921   *   _class : class attribute used on the label tag
 922   *   _text  : Text to display before the input. Not escaped.
 923   * Other attributes are passed to buildAttributes() for the input tag.
 924   *
 925   * @author  Tom N Harris <tnharris@whoopdedo.org>
 926   *
 927   * @param array $attrs attributes
 928   * @return string html
 929   */
 930  function form_passwordfield($attrs) {
 931      // mandatory attributes
 932      unset($attrs['type']);
 933      $s = '<label';
 934      if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
 935      if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
 936      $s .= '><span>'.$attrs['_text'].'</span> ';
 937      $s .= '<input type="password" '. buildAttributes($attrs,true) .' /></label>';
 938      if (preg_match('/(^| )block($| )/', $attrs['_class']))
 939          $s .= '<br />';
 940      return $s;
 941  }
 942  
 943  /**
 944   * form_filefield
 945   *
 946   * Print the HTML for a file input field.
 947   *   _class     : class attribute used on the label tag
 948   *   _text      : Text to display before the input. Not escaped
 949   *   _maxlength : Allowed size in byte
 950   *   _accept    : Accepted mime-type
 951   * Other attributes are passed to buildAttributes() for the input tag
 952   *
 953   * @author  Michael Klier <chi@chimeric.de>
 954   *
 955   * @param array $attrs attributes
 956   * @return string html
 957   */
 958  function form_filefield($attrs) {
 959      $s = '<label';
 960      if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
 961      if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
 962      $s .= '><span>'.$attrs['_text'].'</span> ';
 963      $s .= '<input type="file" '. buildAttributes($attrs,true);
 964      if (!empty($attrs['_maxlength'])) $s .= ' maxlength="'.$attrs['_maxlength'].'"';
 965      if (!empty($attrs['_accept'])) $s .= ' accept="'.$attrs['_accept'].'"';
 966      $s .= ' /></label>';
 967      if (preg_match('/(^| )block($| )/', $attrs['_class']))
 968          $s .= '<br />';
 969      return $s;
 970  }
 971  
 972  /**
 973   * form_checkboxfield
 974   *
 975   * Print the HTML for a checkbox input field.
 976   *   _class : class attribute used on the label tag
 977   *   _text  : Text to display after the input. Not escaped.
 978   * Other attributes are passed to buildAttributes() for the input tag.
 979   * If value is an array, a hidden field with the same name and the value
 980   * $attrs['value'][1] is constructed as well.
 981   *
 982   * @author  Tom N Harris <tnharris@whoopdedo.org>
 983   *
 984   * @param array $attrs attributes
 985   * @return string html
 986   */
 987  function form_checkboxfield($attrs) {
 988      // mandatory attributes
 989      unset($attrs['type']);
 990      $s = '<label';
 991      if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
 992      if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
 993      $s .= '>';
 994      if (is_array($attrs['value'])) {
 995          echo '<input type="hidden" name="'. hsc($attrs['name']) .'"'
 996                  .' value="'. hsc($attrs['value'][1]) .'" />';
 997          $attrs['value'] = $attrs['value'][0];
 998      }
 999      $s .= '<input type="checkbox" '. buildAttributes($attrs,true) .' />';
1000      $s .= ' <span>'.$attrs['_text'].'</span></label>';
1001      if (preg_match('/(^| )block($| )/', $attrs['_class']))
1002          $s .= '<br />';
1003      return $s;
1004  }
1005  
1006  /**
1007   * form_radiofield
1008   *
1009   * Print the HTML for a radio button input field.
1010   *   _class : class attribute used on the label tag
1011   *   _text  : Text to display after the input. Not escaped.
1012   * Other attributes are passed to buildAttributes() for the input tag.
1013   *
1014   * @author  Tom N Harris <tnharris@whoopdedo.org>
1015   *
1016   * @param array $attrs attributes
1017   * @return string html
1018   */
1019  function form_radiofield($attrs) {
1020      // mandatory attributes
1021      unset($attrs['type']);
1022      $s = '<label';
1023      if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
1024      if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
1025      $s .= '><input type="radio" '. buildAttributes($attrs,true) .' />';
1026      $s .= ' <span>'.$attrs['_text'].'</span></label>';
1027      if (preg_match('/(^| )block($| )/', $attrs['_class']))
1028          $s .= '<br />';
1029      return $s;
1030  }
1031  
1032  /**
1033   * form_menufield
1034   *
1035   * Print the HTML for a drop-down menu.
1036   *   _options : Array of (value,text,selected) for the menu.
1037   *              Text can be omitted. Text and value are passed to formText()
1038   *              Only one item can be selected.
1039   *   _class : class attribute used on the label tag
1040   *   _text  : Text to display before the menu. Not escaped.
1041   * Other attributes are passed to buildAttributes() for the input tag.
1042   *
1043   * @author  Tom N Harris <tnharris@whoopdedo.org>
1044   *
1045   * @param array $attrs attributes
1046   * @return string html
1047   */
1048  function form_menufield($attrs) {
1049      $attrs['size'] = '1';
1050      $s = '<label';
1051      if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
1052      if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
1053      $s .= '><span>'.$attrs['_text'].'</span>';
1054      $s .= ' <select '. buildAttributes($attrs,true) .'>'.DOKU_LF;
1055      if (!empty($attrs['_options'])) {
1056          $selected = false;
1057  
1058          $cnt = count($attrs['_options']);
1059          for($n=0; $n < $cnt; $n++){
1060              @list($value,$text,$select) = $attrs['_options'][$n];
1061              $p = '';
1062              if (!is_null($text))
1063                  $p .= ' value="'. formText($value) .'"';
1064              else
1065                  $text = $value;
1066              if (!empty($select) && !$selected) {
1067                  $p .= ' selected="selected"';
1068                  $selected = true;
1069              }
1070              $s .= '<option'.$p.'>'. formText($text) .'</option>';
1071          }
1072      } else {
1073          $s .= '<option></option>';
1074      }
1075      $s .= DOKU_LF.'</select></label>';
1076      if (preg_match('/(^| )block($| )/', $attrs['_class']))
1077          $s .= '<br />';
1078      return $s;
1079  }
1080  
1081  /**
1082   * form_listboxfield
1083   *
1084   * Print the HTML for a list box.
1085   *   _options : Array of (value,text,selected) for the list.
1086   *              Text can be omitted. Text and value are passed to formText()
1087   *   _class : class attribute used on the label tag
1088   *   _text  : Text to display before the menu. Not escaped.
1089   * Other attributes are passed to buildAttributes() for the input tag.
1090   *
1091   * @author  Tom N Harris <tnharris@whoopdedo.org>
1092   *
1093   * @param array $attrs attributes
1094   * @return string html
1095   */
1096  function form_listboxfield($attrs) {
1097      $s = '<label';
1098      if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
1099      if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
1100      $s .= '><span>'.$attrs['_text'].'</span> ';
1101      $s .= '<select '. buildAttributes($attrs,true) .'>'.DOKU_LF;
1102      if (!empty($attrs['_options'])) {
1103          foreach ($attrs['_options'] as $opt) {
1104              @list($value, $text, $select, $disabled) = $opt;
1105              $p = '';
1106              if (is_null($text)) $text = $value;
1107              $p .= ' value="'. formText($value) .'"';
1108              if (!empty($select)) $p .= ' selected="selected"';
1109              if ($disabled) $p .= ' disabled="disabled"';
1110              $s .= '<option'.$p.'>'. formText($text) .'</option>';
1111          }
1112      } else {
1113          $s .= '<option></option>';
1114      }
1115      $s .= DOKU_LF.'</select></label>';
1116      if (preg_match('/(^| )block($| )/', $attrs['_class']))
1117          $s .= '<br />';
1118      return $s;
1119  }