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