xref: /dokuwiki/inc/form.php (revision 8c7c53b0321a3cd3116b8d3b2ad27863a38dece7) 
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 */
35class 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 * form_makeTag
339 *
340 * Create a form element for a non-specific empty tag.
341 *
342 * @param   string  $tag    Tag name.
343 * @param   array   $attrs  Optional attributes.
344 * @return  array   pseudo-tag
345 *
346 * @author  Tom N Harris <tnharris@whoopdedo.org>
347 */
348function form_makeTag($tag, $attrs=array()) {
349    $elem = array('_elem'=>'tag', '_tag'=>$tag);
350    return array_merge($elem, $attrs);
351}
352
353/**
354 * form_makeOpenTag
355 *
356 * Create a form element for a non-specific opening tag.
357 * Remember to put a matching close tag after this as well.
358 *
359 * @param   string  $tag    Tag name.
360 * @param   array   $attrs  Optional attributes.
361 * @return  array   pseudo-tag
362 *
363 * @author  Tom N Harris <tnharris@whoopdedo.org>
364 */
365function form_makeOpenTag($tag, $attrs=array()) {
366    $elem = array('_elem'=>'opentag', '_tag'=>$tag);
367    return array_merge($elem, $attrs);
368}
369
370/**
371 * form_makeCloseTag
372 *
373 * Create a form element for a non-specific closing tag.
374 * Careless use of this will result in invalid XHTML.
375 *
376 * @param   string  $tag    Tag name.
377 * @return  array   pseudo-tag
378 *
379 * @author  Tom N Harris <tnharris@whoopdedo.org>
380 */
381function form_makeCloseTag($tag) {
382    return array('_elem'=>'closetag', '_tag'=>$tag);
383}
384
385/**
386 * form_makeWikiText
387 *
388 * Create a form element for a textarea containing wiki text.
389 * Only one wikitext element is allowed on a page. It will have
390 * a name of 'wikitext' and id 'wiki__text'. The text will
391 * be passed to formText() before printing.
392 *
393 * @param   string  $text   Text to fill the field with.
394 * @param   array   $attrs  Optional attributes.
395 * @return  array   pseudo-tag
396 *
397 * @author  Tom N Harris <tnharris@whoopdedo.org>
398 */
399function form_makeWikiText($text, $attrs=array()) {
400    $elem = array('_elem'=>'wikitext', '_text'=>$text,
401                        'class'=>'edit', 'cols'=>'80', 'rows'=>'10');
402    return array_merge($elem, $attrs);
403}
404
405/**
406 * form_makeButton
407 *
408 * Create a form element for an action button.
409 * A title will automatically be generated using the value and
410 * accesskey attributes, unless you provide one.
411 *
412 * @param   string  $type   Type attribute. 'submit' or 'cancel'
413 * @param   string  $act    Wiki action of the button, will be used as the do= parameter
414 * @param   string  $value  (optional) Displayed label. Uses $act if not provided.
415 * @param   array   $attrs  Optional attributes.
416 * @return  array   pseudo-tag
417 *
418 * @author  Tom N Harris <tnharris@whoopdedo.org>
419 */
420function form_makeButton($type, $act, $value='', $attrs=array()) {
421    if ($value == '') $value = $act;
422    $elem = array('_elem'=>'button', 'type'=>$type, '_action'=>$act,
423                        'value'=>$value);
424    if (!empty($attrs['accesskey']) && empty($attrs['title'])) {
425        $attrs['title'] = $value .' ['. strtoupper($attrs['accesskey']) .']';
426    }
427    return array_merge($elem, $attrs);
428}
429
430/**
431 * form_makeField
432 *
433 * Create a form element for a labelled input element.
434 * The label text will be printed before the input.
435 *
436 * @param   string  $type   Type attribute of input.
437 * @param   string  $name   Name attribute of the input.
438 * @param   string  $value  (optional) Default value.
439 * @param   string  $class  Class attribute of the label. If this is 'block',
440 *                          then a line break will be added after the field.
441 * @param   string  $label  Label that will be printed before the input.
442 * @param   string  $id     ID attribute of the input. If set, the label will
443 *                          reference it with a 'for' attribute.
444 * @param   array   $attrs  Optional attributes.
445 * @return  array   pseudo-tag
446 *
447 * @author  Tom N Harris <tnharris@whoopdedo.org>
448 */
449function form_makeField($type, $name, $value='', $label=null, $id='', $class='', $attrs=array()) {
450    if (is_null($label)) $label = $name;
451    $elem = array('_elem'=>'field', '_text'=>$label, '_class'=>$class,
452                        'type'=>$type, 'id'=>$id, 'name'=>$name, 'value'=>$value);
453    return array_merge($elem, $attrs);
454}
455
456/**
457 * form_makeFieldRight
458 *
459 * Create a form element for a labelled input element.
460 * The label text will be printed after the input.
461 *
462 * @see     form_makeField
463 * @author  Tom N Harris <tnharris@whoopdedo.org>
464 *
465 * @param string $type
466 * @param string $name
467 * @param string $value
468 * @param null|string $label
469 * @param string $id
470 * @param string $class
471 * @param array $attrs
472 *
473 * @return array
474 */
475function form_makeFieldRight($type, $name, $value='', $label=null, $id='', $class='', $attrs=array()) {
476    if (is_null($label)) $label = $name;
477    $elem = array('_elem'=>'fieldright', '_text'=>$label, '_class'=>$class,
478                        'type'=>$type, 'id'=>$id, 'name'=>$name, 'value'=>$value);
479    return array_merge($elem, $attrs);
480}
481
482/**
483 * form_makeTextField
484 *
485 * Create a form element for a text input element with label.
486 *
487 * @see     form_makeField
488 * @author  Tom N Harris <tnharris@whoopdedo.org>
489 *
490 * @param string $name
491 * @param string $value
492 * @param null|string $label
493 * @param string $id
494 * @param string $class
495 * @param array $attrs
496 *
497 * @return array
498 */
499function form_makeTextField($name, $value='', $label=null, $id='', $class='', $attrs=array()) {
500    if (is_null($label)) $label = $name;
501    $elem = array('_elem'=>'textfield', '_text'=>$label, '_class'=>$class,
502                        'id'=>$id, 'name'=>$name, 'value'=>$value, 'class'=>'edit');
503    return array_merge($elem, $attrs);
504}
505
506/**
507 * form_makePasswordField
508 *
509 * Create a form element for a password input element with label.
510 * Password elements have no default value, for obvious reasons.
511 *
512 * @see     form_makeField
513 * @author  Tom N Harris <tnharris@whoopdedo.org>
514 *
515 * @param string $name
516 * @param null|string $label
517 * @param string $id
518 * @param string $class
519 * @param array $attrs
520 *
521 * @return array
522 */
523function form_makePasswordField($name, $label=null, $id='', $class='', $attrs=array()) {
524    if (is_null($label)) $label = $name;
525    $elem = array('_elem'=>'passwordfield', '_text'=>$label, '_class'=>$class,
526                        'id'=>$id, 'name'=>$name, 'class'=>'edit');
527    return array_merge($elem, $attrs);
528}
529
530/**
531 * form_makeFileField
532 *
533 * Create a form element for a file input element with label
534 *
535 * @see     form_makeField
536 * @author  Michael Klier <chi@chimeric.de>
537 *
538 * @param string $name
539 * @param null|string $label
540 * @param string $id
541 * @param string $class
542 * @param array $attrs
543 *
544 * @return array
545 */
546function form_makeFileField($name, $label=null, $id='', $class='', $attrs=array()) {
547    if (is_null($label)) $label = $name;
548    $elem = array('_elem'=>'filefield', '_text'=>$label, '_class'=>$class,
549                        'id'=>$id, 'name'=>$name, 'class'=>'edit');
550    return array_merge($elem, $attrs);
551}
552
553/**
554 * form_makeCheckboxField
555 *
556 * Create a form element for a checkbox input element with label.
557 * If $value is an array, a hidden field with the same name and the value
558 * $value[1] is constructed as well.
559 *
560 * @see     form_makeFieldRight
561 * @author  Tom N Harris <tnharris@whoopdedo.org>
562 *
563 * @param string $name
564 * @param string $value
565 * @param null|string $label
566 * @param string $id
567 * @param string $class
568 * @param array $attrs
569 *
570 * @return array
571 */
572function form_makeCheckboxField($name, $value='1', $label=null, $id='', $class='', $attrs=array()) {
573    if (is_null($label)) $label = $name;
574    if (is_null($value) || $value=='') $value='0';
575    $elem = array('_elem'=>'checkboxfield', '_text'=>$label, '_class'=>$class,
576                        'id'=>$id, 'name'=>$name, 'value'=>$value);
577    return array_merge($elem, $attrs);
578}
579
580/**
581 * form_makeRadioField
582 *
583 * Create a form element for a radio button input element with label.
584 *
585 * @see     form_makeFieldRight
586 * @author  Tom N Harris <tnharris@whoopdedo.org>
587 *
588 * @param string $name
589 * @param string $value
590 * @param null|string $label
591 * @param string $id
592 * @param string $class
593 * @param array $attrs
594 *
595 * @return array
596 */
597function form_makeRadioField($name, $value='1', $label=null, $id='', $class='', $attrs=array()) {
598    if (is_null($label)) $label = $name;
599    if (is_null($value) || $value=='') $value='0';
600    $elem = array('_elem'=>'radiofield', '_text'=>$label, '_class'=>$class,
601                        'id'=>$id, 'name'=>$name, 'value'=>$value);
602    return array_merge($elem, $attrs);
603}
604
605/**
606 * form_makeMenuField
607 *
608 * Create a form element for a drop-down menu with label.
609 * The list of values can be strings, arrays of (value,text),
610 * or an associative array with the values as keys and labels as values.
611 * An item is selected by supplying its value or integer index.
612 * If the list of values is an associative array, the selected item must be
613 * a string.
614 *
615 * @author  Tom N Harris <tnharris@whoopdedo.org>
616 *
617 * @param string           $name     Name attribute of the input.
618 * @param string[]|array[] $values   The list of values can be strings, arrays of (value,text),
619 *                                   or an associative array with the values as keys and labels as values.
620 * @param string|int       $selected default selected value, string or index number
621 * @param string           $class    Class attribute of the label. If this is 'block',
622 *                                   then a line break will be added after the field.
623 * @param string           $label    Label that will be printed before the input.
624 * @param string           $id       ID attribute of the input. If set, the label will
625 *                                   reference it with a 'for' attribute.
626 * @param array            $attrs    Optional attributes.
627 * @return array   pseudo-tag
628 */
629function form_makeMenuField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) {
630    if (is_null($label)) $label = $name;
631    $options = array();
632    reset($values);
633    // FIXME: php doesn't know the difference between a string and an integer
634    if (is_string(key($values))) {
635        foreach ($values as $val => $text) {
636            $options[] = array($val, $text, (!is_null($selected) && $val==$selected));
637        }
638    } else {
639        if (is_integer($selected)) $selected = $values[$selected];
640        foreach ($values as $val) {
641            if (is_array($val))
642                @list($val, $text) = $val;
643            else
644                $text = null;
645            $options[] = array($val, $text, $val===$selected);
646        }
647    }
648    $elem = array('_elem'=>'menufield', '_options'=>$options, '_text'=>$label, '_class'=>$class,
649                        'id'=>$id, 'name'=>$name);
650    return array_merge($elem, $attrs);
651}
652
653/**
654 * form_makeListboxField
655 *
656 * Create a form element for a list box with label.
657 * The list of values can be strings, arrays of (value,text),
658 * or an associative array with the values as keys and labels as values.
659 * Items are selected by supplying its value or an array of values.
660 *
661 * @author  Tom N Harris <tnharris@whoopdedo.org>
662 *
663 * @param string           $name     Name attribute of the input.
664 * @param string[]|array[] $values   The list of values can be strings, arrays of (value,text),
665 *                                   or an associative array with the values as keys and labels as values.
666 * @param array|string     $selected value or array of values of the items that need to be selected
667 * @param string           $class    Class attribute of the label. If this is 'block',
668 *                                   then a line break will be added after the field.
669 * @param string           $label    Label that will be printed before the input.
670 * @param string           $id       ID attribute of the input. If set, the label will
671 *                                   reference it with a 'for' attribute.
672 * @param array            $attrs    Optional attributes.
673 * @return array   pseudo-tag
674 */
675function form_makeListboxField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) {
676    if (is_null($label)) $label = $name;
677    $options = array();
678    reset($values);
679    if (is_null($selected) || $selected == '') {
680        $selected = array();
681    } elseif (!is_array($selected)) {
682        $selected = array($selected);
683    }
684    // FIXME: php doesn't know the difference between a string and an integer
685    if (is_string(key($values))) {
686        foreach ($values as $val => $text) {
687            $options[] = array($val, $text, in_array($val, $selected));
688        }
689    } else {
690        foreach ($values as $val) {
691            $disabled = false;
692            if (is_array($val)) {
693                @list($val, $text, $disabled) = $val;
694            } else {
695                $text = null;
696            }
697            $options[] = array($val, $text, in_array($val, $selected), $disabled);
698        }
699    }
700    $elem = array('_elem'=>'listboxfield', '_options'=>$options, '_text'=>$label, '_class'=>$class,
701                        'id'=>$id, 'name'=>$name);
702    return array_merge($elem, $attrs);
703}
704
705/**
706 * form_tag
707 *
708 * Print the HTML for a generic empty tag.
709 * Requires '_tag' key with name of the tag.
710 * Attributes are passed to buildAttributes()
711 *
712 * @author  Tom N Harris <tnharris@whoopdedo.org>
713 *
714 * @param array $attrs attributes
715 * @return string html of tag
716 */
717function form_tag($attrs) {
718    return '<'.$attrs['_tag'].' '. buildAttributes($attrs, true) .'/>';
719}
720
721/**
722 * form_opentag
723 *
724 * Print the HTML for a generic opening tag.
725 * Requires '_tag' key with name of the tag.
726 * Attributes are passed to buildAttributes()
727 *
728 * @author  Tom N Harris <tnharris@whoopdedo.org>
729 *
730 * @param array $attrs attributes
731 * @return string html of tag
732 */
733function form_opentag($attrs) {
734    return '<'.$attrs['_tag'].' '. buildAttributes($attrs, true) .'>';
735}
736
737/**
738 * form_closetag
739 *
740 * Print the HTML for a generic closing tag.
741 * Requires '_tag' key with name of the tag.
742 * There are no attributes.
743 *
744 * @author  Tom N Harris <tnharris@whoopdedo.org>
745 *
746 * @param array $attrs attributes
747 * @return string html of tag
748 */
749function form_closetag($attrs) {
750    return '</'.$attrs['_tag'].'>';
751}
752
753/**
754 * form_openfieldset
755 *
756 * Print the HTML for an opening fieldset tag.
757 * Uses the '_legend' key.
758 * Attributes are passed to buildAttributes()
759 *
760 * @author  Tom N Harris <tnharris@whoopdedo.org>
761 *
762 * @param array $attrs attributes
763 * @return string html
764 */
765function form_openfieldset($attrs) {
766    $s = '<fieldset '. buildAttributes($attrs, true) .'>';
767    if (!is_null($attrs['_legend'])) $s .= '<legend>'.$attrs['_legend'].'</legend>';
768    return $s;
769}
770
771/**
772 * form_closefieldset
773 *
774 * Print the HTML for a closing fieldset tag.
775 * There are no attributes.
776 *
777 * @author  Tom N Harris <tnharris@whoopdedo.org>
778 *
779 * @return string html
780 */
781function form_closefieldset() {
782    return '</fieldset>';
783}
784
785/**
786 * form_hidden
787 *
788 * Print the HTML for a hidden input element.
789 * Uses only 'name' and 'value' attributes.
790 * Value is passed to formText()
791 *
792 * @author  Tom N Harris <tnharris@whoopdedo.org>
793 *
794 * @param array $attrs attributes
795 * @return string html
796 */
797function form_hidden($attrs) {
798    return '<input type="hidden" name="'.$attrs['name'].'" value="'. formText($attrs['value']) .'" />';
799}
800
801/**
802 * form_wikitext
803 *
804 * Print the HTML for the wiki textarea.
805 * Requires '_text' with default text of the field.
806 * Text will be passed to formText(), attributes to buildAttributes()
807 *
808 * @author  Tom N Harris <tnharris@whoopdedo.org>
809 *
810 * @param array $attrs attributes
811 * @return string html
812 */
813function form_wikitext($attrs) {
814    // mandatory attributes
815    unset($attrs['name']);
816    unset($attrs['id']);
817    return '<textarea name="wikitext" id="wiki__text" dir="auto" '
818                . buildAttributes($attrs, true).'>'.DOKU_LF
819                . formText($attrs['_text'])
820                .'</textarea>';
821}
822
823/**
824 * form_button
825 *
826 * Print the HTML for a form button.
827 * If '_action' is set, the button name will be "do[_action]".
828 * Other attributes are passed to buildAttributes()
829 *
830 * @author  Tom N Harris <tnharris@whoopdedo.org>
831 *
832 * @param array $attrs attributes
833 * @return string html
834 */
835function form_button($attrs) {
836    $p = (!empty($attrs['_action'])) ? 'name="do['.$attrs['_action'].']" ' : '';
837    $value = $attrs['value'];
838    unset($attrs['value']);
839    return '<button '.$p. buildAttributes($attrs, true) .'>'.$value.'</button>';
840}
841
842/**
843 * form_field
844 *
845 * Print the HTML for a form input field.
846 *   _class : class attribute used on the label tag
847 *   _text  : Text to display before the input. Not escaped.
848 * Other attributes are passed to buildAttributes() for the input tag.
849 *
850 * @author  Tom N Harris <tnharris@whoopdedo.org>
851 *
852 * @param array $attrs attributes
853 * @return string html
854 */
855function form_field($attrs) {
856    $s = '<label';
857    if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
858    if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
859    $s .= '><span>'.$attrs['_text'].'</span>';
860    $s .= ' <input '. buildAttributes($attrs, true) .' /></label>';
861    if (preg_match('/(^| )block($| )/', $attrs['_class']))
862        $s .= '<br />';
863    return $s;
864}
865
866/**
867 * form_fieldright
868 *
869 * Print the HTML for a form input field. (right-aligned)
870 *   _class : class attribute used on the label tag
871 *   _text  : Text to display after the input. Not escaped.
872 * Other attributes are passed to buildAttributes() for the input tag.
873 *
874 * @author  Tom N Harris <tnharris@whoopdedo.org>
875 *
876 * @param array $attrs attributes
877 * @return string html
878 */
879function form_fieldright($attrs) {
880    $s = '<label';
881    if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
882    if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
883    $s .= '><input '. buildAttributes($attrs, true) .' />';
884    $s .= ' <span>'.$attrs['_text'].'</span></label>';
885    if (preg_match('/(^| )block($| )/', $attrs['_class']))
886        $s .= '<br />';
887    return $s;
888}
889
890/**
891 * form_textfield
892 *
893 * Print the HTML for a text input field.
894 *   _class : class attribute used on the label tag
895 *   _text  : Text to display before the input. Not escaped.
896 * Other attributes are passed to buildAttributes() for the input tag.
897 *
898 * @author  Tom N Harris <tnharris@whoopdedo.org>
899 *
900 * @param array $attrs attributes
901 * @return string html
902 */
903function form_textfield($attrs) {
904    // mandatory attributes
905    unset($attrs['type']);
906    $s = '<label';
907    if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
908    if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
909    $s .= '><span>'.$attrs['_text'].'</span> ';
910    $s .= '<input type="text" '. buildAttributes($attrs, true) .' /></label>';
911    if (preg_match('/(^| )block($| )/', $attrs['_class']))
912        $s .= '<br />';
913    return $s;
914}
915
916/**
917 * form_passwordfield
918 *
919 * Print the HTML for a password input field.
920 *   _class : class attribute used on the label tag
921 *   _text  : Text to display before the input. Not escaped.
922 * Other attributes are passed to buildAttributes() for the input tag.
923 *
924 * @author  Tom N Harris <tnharris@whoopdedo.org>
925 *
926 * @param array $attrs attributes
927 * @return string html
928 */
929function form_passwordfield($attrs) {
930    // mandatory attributes
931    unset($attrs['type']);
932    $s = '<label';
933    if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
934    if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
935    $s .= '><span>'.$attrs['_text'].'</span> ';
936    $s .= '<input type="password" '. buildAttributes($attrs, true) .' /></label>';
937    if (preg_match('/(^| )block($| )/', $attrs['_class']))
938        $s .= '<br />';
939    return $s;
940}
941
942/**
943 * form_filefield
944 *
945 * Print the HTML for a file input field.
946 *   _class     : class attribute used on the label tag
947 *   _text      : Text to display before the input. Not escaped
948 *   _maxlength : Allowed size in byte
949 *   _accept    : Accepted mime-type
950 * Other attributes are passed to buildAttributes() for the input tag
951 *
952 * @author  Michael Klier <chi@chimeric.de>
953 *
954 * @param array $attrs attributes
955 * @return string html
956 */
957function form_filefield($attrs) {
958    $s = '<label';
959    if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
960    if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
961    $s .= '><span>'.$attrs['_text'].'</span> ';
962    $s .= '<input type="file" '. buildAttributes($attrs, true);
963    if (!empty($attrs['_maxlength'])) $s .= ' maxlength="'.$attrs['_maxlength'].'"';
964    if (!empty($attrs['_accept'])) $s .= ' accept="'.$attrs['_accept'].'"';
965    $s .= ' /></label>';
966    if (preg_match('/(^| )block($| )/', $attrs['_class']))
967        $s .= '<br />';
968    return $s;
969}
970
971/**
972 * form_checkboxfield
973 *
974 * Print the HTML for a checkbox input field.
975 *   _class : class attribute used on the label tag
976 *   _text  : Text to display after the input. Not escaped.
977 * Other attributes are passed to buildAttributes() for the input tag.
978 * If value is an array, a hidden field with the same name and the value
979 * $attrs['value'][1] is constructed as well.
980 *
981 * @author  Tom N Harris <tnharris@whoopdedo.org>
982 *
983 * @param array $attrs attributes
984 * @return string html
985 */
986function form_checkboxfield($attrs) {
987    // mandatory attributes
988    unset($attrs['type']);
989    $s = '<label';
990    if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
991    if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
992    $s .= '>';
993    if (is_array($attrs['value'])) {
994        echo '<input type="hidden" name="'. hsc($attrs['name']) .'"'
995                .' value="'. hsc($attrs['value'][1]) .'" />';
996        $attrs['value'] = $attrs['value'][0];
997    }
998    $s .= '<input type="checkbox" '. buildAttributes($attrs, true) .' />';
999    $s .= ' <span>'.$attrs['_text'].'</span></label>';
1000    if (preg_match('/(^| )block($| )/', $attrs['_class']))
1001        $s .= '<br />';
1002    return $s;
1003}
1004
1005/**
1006 * form_radiofield
1007 *
1008 * Print the HTML for a radio button input field.
1009 *   _class : class attribute used on the label tag
1010 *   _text  : Text to display after the input. Not escaped.
1011 * Other attributes are passed to buildAttributes() for the input tag.
1012 *
1013 * @author  Tom N Harris <tnharris@whoopdedo.org>
1014 *
1015 * @param array $attrs attributes
1016 * @return string html
1017 */
1018function form_radiofield($attrs) {
1019    // mandatory attributes
1020    unset($attrs['type']);
1021    $s = '<label';
1022    if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
1023    if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
1024    $s .= '><input type="radio" '. buildAttributes($attrs, true) .' />';
1025    $s .= ' <span>'.$attrs['_text'].'</span></label>';
1026    if (preg_match('/(^| )block($| )/', $attrs['_class']))
1027        $s .= '<br />';
1028    return $s;
1029}
1030
1031/**
1032 * form_menufield
1033 *
1034 * Print the HTML for a drop-down menu.
1035 *   _options : Array of (value,text,selected) for the menu.
1036 *              Text can be omitted. Text and value are passed to formText()
1037 *              Only one item can be selected.
1038 *   _class : class attribute used on the label tag
1039 *   _text  : Text to display before the menu. Not escaped.
1040 * Other attributes are passed to buildAttributes() for the input tag.
1041 *
1042 * @author  Tom N Harris <tnharris@whoopdedo.org>
1043 *
1044 * @param array $attrs attributes
1045 * @return string html
1046 */
1047function form_menufield($attrs) {
1048    $attrs['size'] = '1';
1049    $s = '<label';
1050    if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
1051    if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
1052    $s .= '><span>'.$attrs['_text'].'</span>';
1053    $s .= ' <select '. buildAttributes($attrs, true) .'>'.DOKU_LF;
1054    if (!empty($attrs['_options'])) {
1055        $selected = false;
1056
1057        $cnt = count($attrs['_options']);
1058        for($n=0; $n < $cnt; $n++){
1059            @list($value,$text,$select) = $attrs['_options'][$n];
1060            $p = '';
1061            if (!is_null($text))
1062                $p .= ' value="'. formText($value) .'"';
1063            else
1064                $text = $value;
1065            if (!empty($select) && !$selected) {
1066                $p .= ' selected="selected"';
1067                $selected = true;
1068            }
1069            $s .= '<option'.$p.'>'. formText($text) .'</option>';
1070        }
1071    } else {
1072        $s .= '<option></option>';
1073    }
1074    $s .= DOKU_LF.'</select></label>';
1075    if (preg_match('/(^| )block($| )/', $attrs['_class']))
1076        $s .= '<br />';
1077    return $s;
1078}
1079
1080/**
1081 * form_listboxfield
1082 *
1083 * Print the HTML for a list box.
1084 *   _options : Array of (value,text,selected) for the list.
1085 *              Text can be omitted. Text and value are passed to formText()
1086 *   _class : class attribute used on the label tag
1087 *   _text  : Text to display before the menu. Not escaped.
1088 * Other attributes are passed to buildAttributes() for the input tag.
1089 *
1090 * @author  Tom N Harris <tnharris@whoopdedo.org>
1091 *
1092 * @param array $attrs attributes
1093 * @return string html
1094 */
1095function form_listboxfield($attrs) {
1096    $s = '<label';
1097    if ($attrs['_class']) $s .= ' class="'.$attrs['_class'].'"';
1098    if (!empty($attrs['id'])) $s .= ' for="'.$attrs['id'].'"';
1099    $s .= '><span>'.$attrs['_text'].'</span> ';
1100    $s .= '<select '. buildAttributes($attrs, true) .'>'.DOKU_LF;
1101    if (!empty($attrs['_options'])) {
1102        foreach ($attrs['_options'] as $opt) {
1103            @list($value, $text, $select, $disabled) = $opt;
1104            $p = '';
1105            if (is_null($text)) $text = $value;
1106            $p .= ' value="'. formText($value) .'"';
1107            if (!empty($select)) $p .= ' selected="selected"';
1108            if ($disabled) $p .= ' disabled="disabled"';
1109            $s .= '<option'.$p.'>'. formText($text) .'</option>';
1110        }
1111    } else {
1112        $s .= '<option></option>';
1113    }
1114    $s .= DOKU_LF.'</select></label>';
1115    if (preg_match('/(^| )block($| )/', $attrs['_class']))
1116        $s .= '<br />';
1117    return $s;
1118}
1119