493b168d |
1 | <?php |
2 | /** |
ed6d3334 |
3 | * forms.php - html form functions |
493b168d |
4 | * |
6c84ba1e |
5 | * Copyright (c) 2004-2005 The SquirrelMail Project Team |
493b168d |
6 | * Licensed under the GNU GPL. For full terms see the file COPYING. |
7 | * |
8 | * Functions to build HTML forms in a safe and consistent manner. |
15623730 |
9 | * All attribute values are sanitized with htmlspecialchars(). |
493b168d |
10 | * |
ed6d3334 |
11 | * Currently functions don't provide simple wrappers for file and |
12 | * image input fields, support only submit and reset buttons and use |
15623730 |
13 | * html input tags for buttons. |
ed6d3334 |
14 | * |
15 | * Since 1.5.1 all form functions should support id tags. Original |
16 | * idea by dugan <at> passwall.com. Tags can be used for Section 508 |
17 | * or WAI compliance. |
18 | * |
19 | * @link http://www.section508.gov/ Section 508 |
20 | * @link http://www.w3.org/WAI/ Web Accessibility Initiative (WAI) |
21 | * @link http://www.w3.org/TR/html4/ W3.org HTML 4.01 form specs |
74f5d33f |
22 | * @version $Id$ |
493b168d |
23 | * @package squirrelmail |
74f5d33f |
24 | * @subpackage forms |
ed6d3334 |
25 | * @since 1.4.3 and 1.5.1 |
493b168d |
26 | */ |
27 | |
28 | /** |
29 | * Helper function to create form fields, not to be called directly, |
30 | * only by other functions below. |
ed6d3334 |
31 | * @param string $type type of input field. Possible values (html 4.01 |
32 | * specs.): text, password, checkbox, radio, submit, reset, file, |
33 | * hidden, image, button. |
34 | * @param string $name form field name |
35 | * @param string $value initial field value |
36 | * @param string $attributes extra attributes |
37 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
38 | * @return string html formated input field |
39 | * @deprecated use other functions that provide simple wrappers to this function |
493b168d |
40 | */ |
9986098e |
41 | function addInputField($type, $name = null, $value = null, $attributes = '', $id = null) { |
10ff256e |
42 | return '<input type="'.$type.'"'. |
745eb9e2 |
43 | ($name !== null ? ' name="'.htmlspecialchars($name).'"' : ''). |
f8a1ed5a |
44 | ($id !== null ? ' id="'.htmlspecialchars($id).'"' |
9986098e |
45 | : ($name !== null ? ' id="'.htmlspecialchars($name).'"' : '')). |
745eb9e2 |
46 | ($value !== null ? ' value="'.htmlspecialchars($value).'"' : ''). |
fad34a61 |
47 | $attributes . " />\n"; |
493b168d |
48 | } |
49 | |
10ff256e |
50 | /** |
51 | * Password input field |
ed6d3334 |
52 | * @param string $name field name |
53 | * @param string $value initial password value |
54 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
55 | * @return string html formated password field |
10ff256e |
56 | */ |
ed6d3334 |
57 | function addPwField($name , $value = null, $id = null) { |
58 | return addInputField('password', $name , $value, '', $id); |
10ff256e |
59 | } |
60 | |
493b168d |
61 | /** |
62 | * Form checkbox |
ed6d3334 |
63 | * @param string $name field name |
64 | * @param boolean $checked controls if field is checked |
65 | * @param string $value |
66 | * @param string $xtra (since 1.5.1) extra field attributes |
67 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
68 | * @return string html formated checkbox field |
493b168d |
69 | */ |
ed6d3334 |
70 | function addCheckBox($name, $checked = false, $value = null, $xtra = '', $id = null) { |
493b168d |
71 | return addInputField('checkbox', $name, $value, |
ed6d3334 |
72 | ($checked ? ' checked="checked"' : '') . ' ' . $xtra, $id); |
493b168d |
73 | } |
74 | |
75 | /** |
76 | * Form radio box |
ed6d3334 |
77 | * @param string $name field name |
78 | * @param boolean $checked controls if field is selected |
79 | * @param string $value |
80 | * @param string $id (since 1.5.1) assigns unique identifier to an element. |
81 | * Defaults to combined $name and $value string |
82 | * @return string html formated radio box |
493b168d |
83 | */ |
ed6d3334 |
84 | function addRadioBox($name, $checked = false, $value = null, $id = '') { |
85 | if (empty($id)) { |
86 | $id = $name . $value; |
87 | } |
324ac3c5 |
88 | return addInputField('radio', $name, $value, |
ed6d3334 |
89 | ($checked ? ' checked="checked"' : ''), $id); |
493b168d |
90 | } |
91 | |
92 | /** |
93 | * A hidden form field. |
ed6d3334 |
94 | * @param string $name field name |
95 | * @param string $value field value |
96 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
97 | * @return html formated hidden form field |
493b168d |
98 | */ |
ed6d3334 |
99 | function addHidden($name, $value, $id = null) { |
100 | return addInputField('hidden', $name, $value, '', $id); |
493b168d |
101 | } |
102 | |
103 | /** |
104 | * An input textbox. |
ed6d3334 |
105 | * @param string $name field name |
106 | * @param string $value initial field value |
107 | * @param integer $size field size (number of characters) |
108 | * @param integer $maxlength maximum number of characters the user may enter |
109 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
110 | * @return string html formated text input field |
493b168d |
111 | */ |
ed6d3334 |
112 | function addInput($name, $value = '', $size = 0, $maxlength = 0, $id = null) { |
493b168d |
113 | |
114 | $attr = ''; |
115 | if ($size) { |
116 | $attr.= ' size="'.(int)$size.'"'; |
117 | } |
118 | if ($maxlength) { |
119 | $attr.= ' maxlength="'.(int)$maxlength .'"'; |
120 | } |
121 | |
ed6d3334 |
122 | return addInputField('text', $name, $value, $attr, $id); |
493b168d |
123 | } |
124 | |
493b168d |
125 | /** |
126 | * Function to create a selectlist from an array. |
ed6d3334 |
127 | * @param string $name field name |
128 | * @param array $values field values array ( key => value ) -> <option value="key">value</option> |
129 | * @param mixed $default the key that will be selected |
130 | * @param boolean $usekeys use the keys of the array as option value or not |
131 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
132 | * @return string html formated selection box |
493b168d |
133 | */ |
ed6d3334 |
134 | function addSelect($name, $values, $default = null, $usekeys = false, $id = null) { |
493b168d |
135 | // only one element |
136 | if(count($values) == 1) { |
137 | $k = key($values); $v = array_pop($values); |
ed6d3334 |
138 | return addHidden($name, ($usekeys ? $k:$v), $id). |
745eb9e2 |
139 | htmlspecialchars($v) . "\n"; |
493b168d |
140 | } |
141 | |
ed6d3334 |
142 | if (! is_null($id)) { |
143 | $id = ' id="'.htmlspecialchars($id).'"'; |
144 | $label_open = '<label for="'.htmlspecialchars($id).'">'; |
145 | $label_close = '</label>'; |
146 | } else { |
147 | $id = ''; |
148 | $label_open = ''; |
149 | $label_close = ''; |
150 | } |
151 | |
152 | $ret = '<select name="'.htmlspecialchars($name) . '"' . $id . ">\n"; |
493b168d |
153 | foreach ($values as $k => $v) { |
154 | if(!$usekeys) $k = $v; |
155 | $ret .= '<option value="' . |
745eb9e2 |
156 | htmlspecialchars( $k ) . '"' . |
f79fb61d |
157 | (($default == $k) ? ' selected="selected"' : '') . |
ed6d3334 |
158 | '>' . $label_open . htmlspecialchars($v) . $label_close ."</option>\n"; |
493b168d |
159 | } |
160 | $ret .= "</select>\n"; |
161 | |
162 | return $ret; |
163 | } |
164 | |
10ff256e |
165 | /** |
166 | * Form submission button |
167 | * Note the switched value/name parameters! |
ed6d3334 |
168 | * @param string $value button name |
169 | * @param string $name submitted key name |
170 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
171 | * @return string html formated submit input field |
10ff256e |
172 | */ |
ed6d3334 |
173 | function addSubmit($value, $name = null, $id = null) { |
174 | return addInputField('submit', $name, $value, '', $id); |
10ff256e |
175 | } |
176 | /** |
ed6d3334 |
177 | * Form reset button |
178 | * @param string $value button name |
179 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
180 | * @return string html formated reset input field |
10ff256e |
181 | */ |
ed6d3334 |
182 | function addReset($value, $id = null) { |
183 | return addInputField('reset', null, $value, '', $id); |
10ff256e |
184 | } |
185 | |
493b168d |
186 | /** |
187 | * Textarea form element. |
ed6d3334 |
188 | * @param string $name field name |
189 | * @param string $text initial field value |
190 | * @param integer $cols field width (number of chars) |
191 | * @param integer $rows field height (number of character rows) |
192 | * @param string $attr extra attributes |
193 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
194 | * @return string html formated text area field |
493b168d |
195 | */ |
ed6d3334 |
196 | function addTextArea($name, $text = '', $cols = 40, $rows = 10, $attr = '', $id = '') { |
197 | if (!empty($id)) { |
198 | $id = ' id="'. htmlspecialchars($id) . '"'; |
199 | $label_open = '<label for="'.htmlspecialchars($id).'">'; |
200 | $label_close = '</label>'; |
201 | } else { |
202 | $label_open = ''; |
203 | $label_close = ''; |
204 | } |
745eb9e2 |
205 | return '<textarea name="'.htmlspecialchars($name).'" '. |
8a9f3f9d |
206 | 'rows="'.(int)$rows .'" cols="'.(int)$cols.'" '. |
ed6d3334 |
207 | $attr . $id . '>'. $label_open . htmlspecialchars($text) . $label_close ."</textarea>\n"; |
493b168d |
208 | } |
209 | |
210 | /** |
211 | * Make a <form> start-tag. |
ed6d3334 |
212 | * @param string $action form handler URL |
213 | * @param string $method http method used to submit form data. 'get' or 'post' |
214 | * @param string $name form name used for identification (used for backward |
215 | * compatibility). Use of id is recommended. |
216 | * @param string $enctype content type that is used to submit data. html 4.01 |
217 | * defaults to 'application/x-www-form-urlencoded'. Form with file field needs |
218 | * 'multipart/form-data' encoding type. |
219 | * @param string $charset charset that is used for submitted data |
220 | * @param string $id (since 1.5.1) assigns unique identifier to an element |
221 | * @return string html formated form start string |
493b168d |
222 | */ |
ed6d3334 |
223 | function addForm($action, $method = 'post', $name = '', $enctype = '', $charset = '', $id = '') { |
493b168d |
224 | if($name) { |
225 | $name = ' name="'.$name.'"'; |
226 | } |
227 | if($enctype) { |
228 | $enctype = ' enctype="'.$enctype.'"'; |
229 | } |
230 | if($charset) { |
231 | $charset = ' accept-charset="'.htmlspecialchars($charset).'"'; |
232 | } |
ed6d3334 |
233 | if (!empty($id)) { |
234 | $id = ' id="'.htmlspecialchars($id).'"'; |
235 | } |
493b168d |
236 | |
237 | return '<form action="'. $action .'" method="'. $method .'"'. |
ed6d3334 |
238 | $enctype . $name . $charset . $id . ">\n"; |
493b168d |
239 | } |
240 | |
f8a1ed5a |
241 | ?> |