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