493b168d |
1 | <?php |
4b4abf93 |
2 | |
493b168d |
3 | /** |
ed6d3334 |
4 | * forms.php - html form functions |
493b168d |
5 | * |
ba556ce5 |
6 | * Functions to build forms in a safe and consistent manner. |
15623730 |
7 | * All attribute values are sanitized with htmlspecialchars(). |
ba556ce5 |
8 | //FIXME: I think the Template class might be better place to sanitize inside assign() method |
493b168d |
9 | * |
ed6d3334 |
10 | * Currently functions don't provide simple wrappers for file and |
11 | * image input fields, support only submit and reset buttons and use |
15623730 |
12 | * html input tags for buttons. |
ed6d3334 |
13 | * |
574240f5 |
14 | * Since 1.5.1: |
15 | * |
16 | * * all form functions should support id tags. Original |
17 | * idea by dugan <at> passwall.com. Tags can be used for Section 508 |
18 | * or WAI compliance. |
19 | * |
20 | * * input tag functions accept extra html attributes that can be submitted |
21 | * in $aAttribs array. |
22 | * |
23 | * * default css class attributes are added. |
ed6d3334 |
24 | * |
25 | * @link http://www.section508.gov/ Section 508 |
26 | * @link http://www.w3.org/WAI/ Web Accessibility Initiative (WAI) |
27 | * @link http://www.w3.org/TR/html4/ W3.org HTML 4.01 form specs |
4b5049de |
28 | * @copyright © 2004-2007 The SquirrelMail Project Team |
4b4abf93 |
29 | * @license http://opensource.org/licenses/gpl-license.php GNU Public License |
74f5d33f |
30 | * @version $Id$ |
493b168d |
31 | * @package squirrelmail |
74f5d33f |
32 | * @subpackage forms |
ed6d3334 |
33 | * @since 1.4.3 and 1.5.1 |
493b168d |
34 | */ |
35 | |
36 | /** |
37 | * Helper function to create form fields, not to be called directly, |
38 | * only by other functions below. |
574240f5 |
39 | * |
40 | * Function used different syntax before 1.5.1 |
41 | * @param string $sType type of input field. Possible values (html 4.01 |
ed6d3334 |
42 | * specs.): text, password, checkbox, radio, submit, reset, file, |
43 | * hidden, image, button. |
574240f5 |
44 | * @param array $aAttribs (since 1.5.1) extra attributes. Array key is |
45 | * attribute name, array value is attribute value. Array keys must use |
46 | * lowercase. |
ed6d3334 |
47 | * @return string html formated input field |
48 | * @deprecated use other functions that provide simple wrappers to this function |
493b168d |
49 | */ |
574240f5 |
50 | function addInputField($sType, $aAttribs=array()) { |
51 | $sAttribs = ''; |
52 | // define unique identifier |
53 | if (! isset($aAttribs['id']) && isset($aAttribs['name']) && ! is_null($aAttribs['name'])) { |
5f817a0b |
54 | /** |
55 | * if 'id' is not set, set it to 'name' and replace brackets |
56 | * with underscores. 'name' might contain field name with squire |
57 | * brackets (array). Brackets are not allowed in id (validator.w3.org |
58 | * fails to validate document). According to html 4.01 manual cdata |
59 | * type description, 'name' attribute uses same type, but validator.w3.org |
60 | * does not barf on brackets in 'name' attributes. |
61 | */ |
62 | $aAttribs['id'] = strtr($aAttribs['name'],'[]','__'); |
574240f5 |
63 | } |
ba556ce5 |
64 | |
65 | global $oTemplate; |
66 | |
67 | $oTemplate->assign('type', $sType); |
68 | //FIXME: all the values in the $aAttribs list used to go thru htmlspecialchars()... I would propose that most everything that is assigned to the template should go thru that *in the template class* on its way between here and the actual template file. Otherwise we have to do something like: foreach ($aAttribs as $key => $value) $aAttribs[$key] = htmlspecialchars($value); |
69 | $oTemplate->assign('aAttribs', $aAttribs); |
70 | |
71 | return $oTemplate->fetch('input.tpl'); |
72 | |
493b168d |
73 | } |
74 | |
10ff256e |
75 | /** |
76 | * Password input field |
574240f5 |
77 | * @param string $sName field name |
78 | * @param string $sValue initial password value |
79 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
80 | * @return string html formated password field |
10ff256e |
81 | */ |
574240f5 |
82 | function addPwField($sName, $sValue = null, $aAttribs=array()) { |
83 | $aAttribs['name'] = $sName; |
84 | $aAttribs['value'] = (! is_null($sValue) ? $sValue : ''); |
85 | // add default css |
86 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmpwfield'; |
87 | return addInputField('password',$aAttribs); |
10ff256e |
88 | } |
89 | |
493b168d |
90 | /** |
91 | * Form checkbox |
574240f5 |
92 | * @param string $sName field name |
93 | * @param boolean $bChecked controls if field is checked |
94 | * @param string $sValue |
95 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
96 | * @return string html formated checkbox field |
493b168d |
97 | */ |
574240f5 |
98 | function addCheckBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) { |
99 | $aAttribs['name'] = $sName; |
100 | if ($bChecked) $aAttribs['checked'] = 'checked'; |
101 | if (! is_null($sValue)) $aAttribs['value'] = $sValue; |
102 | // add default css |
103 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox'; |
104 | return addInputField('checkbox',$aAttribs); |
493b168d |
105 | } |
106 | |
107 | /** |
108 | * Form radio box |
574240f5 |
109 | * @param string $sName field name |
110 | * @param boolean $bChecked controls if field is selected |
111 | * @param string $sValue |
112 | * @param array $aAttribs (since 1.5.1) extra attributes. |
ed6d3334 |
113 | * @return string html formated radio box |
493b168d |
114 | */ |
574240f5 |
115 | function addRadioBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) { |
116 | $aAttribs['name'] = $sName; |
117 | if ($bChecked) $aAttribs['checked'] = 'checked'; |
118 | if (! is_null($sValue)) $aAttribs['value'] = $sValue; |
119 | if (! isset($aAttribs['id'])) $aAttribs['id'] = $sName . $sValue; |
120 | // add default css |
121 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox'; |
122 | return addInputField('radio', $aAttribs); |
493b168d |
123 | } |
124 | |
125 | /** |
126 | * A hidden form field. |
574240f5 |
127 | * @param string $sName field name |
128 | * @param string $sValue field value |
129 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
130 | * @return html formated hidden form field |
493b168d |
131 | */ |
574240f5 |
132 | function addHidden($sName, $sValue, $aAttribs=array()) { |
133 | $aAttribs['name'] = $sName; |
134 | $aAttribs['value'] = $sValue; |
135 | // add default css |
136 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmhiddenfield'; |
137 | return addInputField('hidden', $aAttribs); |
493b168d |
138 | } |
139 | |
140 | /** |
141 | * An input textbox. |
574240f5 |
142 | * @param string $sName field name |
143 | * @param string $sValue initial field value |
144 | * @param integer $iSize field size (number of characters) |
145 | * @param integer $iMaxlength maximum number of characters the user may enter |
87745b9c |
146 | * @param array $aAttribs (since 1.5.1) extra attributes - should be given |
147 | * in the form array('attribute_name' => 'attribute_value', ...) |
ed6d3334 |
148 | * @return string html formated text input field |
493b168d |
149 | */ |
574240f5 |
150 | function addInput($sName, $sValue = '', $iSize = 0, $iMaxlength = 0, $aAttribs=array()) { |
151 | $aAttribs['name'] = $sName; |
152 | $aAttribs['value'] = $sValue; |
153 | if ($iSize) $aAttribs['size'] = (int)$iSize; |
154 | if ($iMaxlength) $aAttribs['maxlength'] = (int)$iMaxlength; |
155 | // add default css |
156 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield'; |
157 | return addInputField('text', $aAttribs); |
493b168d |
158 | } |
159 | |
493b168d |
160 | /** |
161 | * Function to create a selectlist from an array. |
42b7c9d4 |
162 | * @param string $sName Field name |
163 | * @param array $aValues Field values array(key => value) results in: |
164 | * <option value="key">value</option>, |
165 | * although if $bUsekeys is FALSE, then it changes to: |
166 | * <option value="value">value</option> |
167 | * @param mixed $default The key(s) that will be selected (it is OK to pass |
168 | * in an array here in the case of multiple select lists) |
169 | * @param boolean $bUsekeys Use the keys of the array as option value or not |
170 | * @param array $aAttribs (since 1.5.1) Extra attributes |
171 | * @param boolean $bMultiple When TRUE, a multiple select list will be shown |
172 | * (OPTIONAL; default is FALSE (single select list)) |
38d93650 |
173 | * @param int $iSize Desired height of multiple select boxes |
174 | * (OPTIONAL; default is SMOPT_SIZE_NORMAL) |
175 | * (only applicable when $bMultiple is TRUE) |
02ded2ae |
176 | * |
ed6d3334 |
177 | * @return string html formated selection box |
574240f5 |
178 | * @todo add attributes argument for option tags and default css |
493b168d |
179 | */ |
38d93650 |
180 | function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array(), $bMultiple = FALSE, $iSize = SMOPT_SIZE_NORMAL) { |
493b168d |
181 | // only one element |
38d93650 |
182 | if (!$bMultiple && count($aValues) == 1) { |
574240f5 |
183 | $k = key($aValues); $v = array_pop($aValues); |
38d93650 |
184 | return addHidden($sName, ($bUsekeys ? $k : $v), $aAttribs) |
185 | . htmlspecialchars($v); |
493b168d |
186 | } |
187 | |
42b7c9d4 |
188 | |
189 | // make sure $default is an array, since multiple select lists |
190 | // need the chance to have more than one default... |
191 | // |
192 | if (!is_array($default)) |
193 | $default = array($default); |
194 | |
195 | |
ba556ce5 |
196 | global $oTemplate; |
ed6d3334 |
197 | |
42b7c9d4 |
198 | //FIXME: all the values in the $aAttribs list and $sName and both the keys and values in $aValues used to go thru htmlspecialchars()... I would propose that most everything that is assigned to the template should go thru that *in the template class* on its way between here and the actual template file. Otherwise we have to do something like: foreach ($aAttribs as $key => $value) $aAttribs[$key] = htmlspecialchars($value); $sName = htmlspecialchars($sName); $aNewValues = array(); foreach ($aValues as $key => $value) $aNewValues[htmlspecialchars($key)] = htmlspecialchars($value); $aValues = $aNewValues; And probably this too because it has to be matched to a value that has already been sanitized: $default = htmlspecialchars($default); (oops, watch out for when $default is an array! (multiple select lists)) |
ba556ce5 |
199 | $oTemplate->assign('aAttribs', $aAttribs); |
200 | $oTemplate->assign('aValues', $aValues); |
201 | $oTemplate->assign('bUsekeys', $bUsekeys); |
202 | $oTemplate->assign('default', $default); |
203 | $oTemplate->assign('name', $sName); |
42b7c9d4 |
204 | $oTemplate->assign('multiple', $bMultiple); |
38d93650 |
205 | $oTemplate->assign('size', $iSize); |
574240f5 |
206 | |
ba556ce5 |
207 | return $oTemplate->fetch('select.tpl'); |
493b168d |
208 | } |
209 | |
02ded2ae |
210 | /** |
211 | * Normal button |
212 | * |
213 | * Note the switched value/name parameters! |
214 | * Note also that regular buttons are not very useful unless |
215 | * used with onclick handlers, thus are only really appropriate |
216 | * if you use them after having checked if JavaScript is turned |
217 | * on by doing this: if (checkForJavascript()) ... |
218 | * |
219 | * @param string $sValue button name |
220 | * @param string $sName key name |
221 | * @param array $aAttribs extra attributes |
222 | * |
223 | * @return string html formated submit input field |
224 | * |
225 | * @since 1.5.2 |
226 | */ |
227 | function addButton($sValue, $sName = null, $aAttribs=array()) { |
228 | $aAttribs['value'] = $sValue; |
229 | if (! is_null($sName)) $aAttribs['name'] = $sName; |
230 | // add default css |
231 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield'; |
232 | return addInputField('button', $aAttribs); |
233 | } |
234 | |
10ff256e |
235 | /** |
236 | * Form submission button |
237 | * Note the switched value/name parameters! |
574240f5 |
238 | * @param string $sValue button name |
239 | * @param string $sName submitted key name |
240 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
241 | * @return string html formated submit input field |
10ff256e |
242 | */ |
574240f5 |
243 | function addSubmit($sValue, $sName = null, $aAttribs=array()) { |
244 | $aAttribs['value'] = $sValue; |
245 | if (! is_null($sName)) $aAttribs['name'] = $sName; |
246 | // add default css |
247 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield'; |
248 | return addInputField('submit', $aAttribs); |
10ff256e |
249 | } |
02ded2ae |
250 | |
10ff256e |
251 | /** |
ed6d3334 |
252 | * Form reset button |
574240f5 |
253 | * @param string $sValue button name |
254 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
255 | * @return string html formated reset input field |
10ff256e |
256 | */ |
574240f5 |
257 | function addReset($sValue, $aAttribs=array()) { |
258 | $aAttribs['value'] = $sValue; |
259 | // add default css |
260 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield'; |
261 | return addInputField('reset', $aAttribs); |
10ff256e |
262 | } |
263 | |
493b168d |
264 | /** |
265 | * Textarea form element. |
ba556ce5 |
266 | * |
267 | * @param string $sName field name |
268 | * @param string $sText initial field value (OPTIONAL; default empty) |
269 | * @param integer $iCols field width (number of chars) (OPTIONAL; default 40) |
270 | * @param integer $iRows field height (number of character rows) (OPTIONAL; default 10) |
271 | * @param array $aAttribs (since 1.5.1) extra attributes (OPTIONAL; default empty) |
272 | * |
ed6d3334 |
273 | * @return string html formated text area field |
ba556ce5 |
274 | * |
493b168d |
275 | */ |
574240f5 |
276 | function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) { |
ba556ce5 |
277 | |
278 | // no longer accept string arguments for attribs; print |
279 | // backtrace to help people fix their code |
02ded2ae |
280 | //FIXME: throw error instead? |
ba556ce5 |
281 | if (!is_array($aAttribs)) { |
282 | echo '$aAttribs argument to addTextArea() must be an array<br /><pre>'; |
283 | debug_print_backtrace(); |
284 | echo '</pre><br />'; |
285 | exit; |
ed6d3334 |
286 | } |
ba556ce5 |
287 | |
02ded2ae |
288 | // add default css |
ba556ce5 |
289 | else if (!isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea'; |
290 | |
291 | global $oTemplate; |
292 | |
293 | //FIXME: all the values in the $aAttribs list as well as $sName and $sText used to go thru htmlspecialchars()... I would propose that most everything that is assigned to the template should go thru that *in the template class* on its way between here and the actual template file. Otherwise we have to do something like: foreach ($aAttribs as $key => $value) $aAttribs[$key] = htmlspecialchars($value); $sName = htmlspecialchars($sName); $sText = htmlspecialchars($sText); |
294 | $oTemplate->assign('aAttribs', $aAttribs); |
295 | $oTemplate->assign('name', $sName); |
296 | $oTemplate->assign('text', $sText); |
297 | $oTemplate->assign('cols', (int)$iCols); |
298 | $oTemplate->assign('rows', (int)$iRows); |
299 | |
300 | return $oTemplate->fetch('textarea.tpl'); |
493b168d |
301 | } |
302 | |
303 | /** |
304 | * Make a <form> start-tag. |
ba556ce5 |
305 | * |
306 | * @param string $sAction form handler URL |
307 | * @param string $sMethod http method used to submit form data. 'get' or 'post' |
308 | * @param string $sName form name used for identification (used for backward |
309 | * compatibility). Use of id is recommended instead. |
574240f5 |
310 | * @param string $sEnctype content type that is used to submit data. html 4.01 |
ba556ce5 |
311 | * defaults to 'application/x-www-form-urlencoded'. Form |
312 | * with file field needs 'multipart/form-data' encoding type. |
574240f5 |
313 | * @param string $sCharset charset that is used for submitted data |
ba556ce5 |
314 | * @param array $aAttribs (since 1.5.1) extra attributes |
315 | * |
ed6d3334 |
316 | * @return string html formated form start string |
ba556ce5 |
317 | * |
493b168d |
318 | */ |
574240f5 |
319 | function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) { |
574240f5 |
320 | |
ba556ce5 |
321 | global $oTemplate; |
574240f5 |
322 | |
ba556ce5 |
323 | //FIXME: all the values in the $aAttribs list as well as $charset used to go thru htmlspecialchars()... I would propose that most everything that is assigned to the template should go thru that *in the template class* on its way between here and the actual template file. Otherwise we have to do something like: foreach ($aAttribs as $key => $value) $aAttribs[$key] = htmlspecialchars($value); $sCharset = htmlspecialchars($sCharset); |
324 | $oTemplate->assign('aAttribs', $aAttribs); |
325 | $oTemplate->assign('name', $sName); |
326 | $oTemplate->assign('method', $sMethod); |
327 | $oTemplate->assign('action', $sAction); |
328 | $oTemplate->assign('enctype', $sEnctype); |
329 | $oTemplate->assign('charset', $sCharset); |
493b168d |
330 | |
ba556ce5 |
331 | return $oTemplate->fetch('form.tpl'); |
493b168d |
332 | } |
ba556ce5 |
333 | |