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)) |
02ded2ae |
173 | * |
ed6d3334 |
174 | * @return string html formated selection box |
574240f5 |
175 | * @todo add attributes argument for option tags and default css |
493b168d |
176 | */ |
42b7c9d4 |
177 | function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array(), $bMultiple = FALSE) { |
493b168d |
178 | // only one element |
574240f5 |
179 | if(count($aValues) == 1) { |
180 | $k = key($aValues); $v = array_pop($aValues); |
181 | return addHidden($sName, ($bUsekeys ? $k:$v), $aAttribs). |
745eb9e2 |
182 | htmlspecialchars($v) . "\n"; |
493b168d |
183 | } |
184 | |
42b7c9d4 |
185 | |
186 | // make sure $default is an array, since multiple select lists |
187 | // need the chance to have more than one default... |
188 | // |
189 | if (!is_array($default)) |
190 | $default = array($default); |
191 | |
192 | |
ba556ce5 |
193 | global $oTemplate; |
ed6d3334 |
194 | |
42b7c9d4 |
195 | //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 |
196 | $oTemplate->assign('aAttribs', $aAttribs); |
197 | $oTemplate->assign('aValues', $aValues); |
198 | $oTemplate->assign('bUsekeys', $bUsekeys); |
199 | $oTemplate->assign('default', $default); |
200 | $oTemplate->assign('name', $sName); |
42b7c9d4 |
201 | $oTemplate->assign('multiple', $bMultiple); |
574240f5 |
202 | |
ba556ce5 |
203 | return $oTemplate->fetch('select.tpl'); |
493b168d |
204 | } |
205 | |
02ded2ae |
206 | /** |
207 | * Normal button |
208 | * |
209 | * Note the switched value/name parameters! |
210 | * Note also that regular buttons are not very useful unless |
211 | * used with onclick handlers, thus are only really appropriate |
212 | * if you use them after having checked if JavaScript is turned |
213 | * on by doing this: if (checkForJavascript()) ... |
214 | * |
215 | * @param string $sValue button name |
216 | * @param string $sName key name |
217 | * @param array $aAttribs extra attributes |
218 | * |
219 | * @return string html formated submit input field |
220 | * |
221 | * @since 1.5.2 |
222 | */ |
223 | function addButton($sValue, $sName = null, $aAttribs=array()) { |
224 | $aAttribs['value'] = $sValue; |
225 | if (! is_null($sName)) $aAttribs['name'] = $sName; |
226 | // add default css |
227 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield'; |
228 | return addInputField('button', $aAttribs); |
229 | } |
230 | |
10ff256e |
231 | /** |
232 | * Form submission button |
233 | * Note the switched value/name parameters! |
574240f5 |
234 | * @param string $sValue button name |
235 | * @param string $sName submitted key name |
236 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
237 | * @return string html formated submit input field |
10ff256e |
238 | */ |
574240f5 |
239 | function addSubmit($sValue, $sName = null, $aAttribs=array()) { |
240 | $aAttribs['value'] = $sValue; |
241 | if (! is_null($sName)) $aAttribs['name'] = $sName; |
242 | // add default css |
243 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield'; |
244 | return addInputField('submit', $aAttribs); |
10ff256e |
245 | } |
02ded2ae |
246 | |
10ff256e |
247 | /** |
ed6d3334 |
248 | * Form reset button |
574240f5 |
249 | * @param string $sValue button name |
250 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
251 | * @return string html formated reset input field |
10ff256e |
252 | */ |
574240f5 |
253 | function addReset($sValue, $aAttribs=array()) { |
254 | $aAttribs['value'] = $sValue; |
255 | // add default css |
256 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield'; |
257 | return addInputField('reset', $aAttribs); |
10ff256e |
258 | } |
259 | |
493b168d |
260 | /** |
261 | * Textarea form element. |
ba556ce5 |
262 | * |
263 | * @param string $sName field name |
264 | * @param string $sText initial field value (OPTIONAL; default empty) |
265 | * @param integer $iCols field width (number of chars) (OPTIONAL; default 40) |
266 | * @param integer $iRows field height (number of character rows) (OPTIONAL; default 10) |
267 | * @param array $aAttribs (since 1.5.1) extra attributes (OPTIONAL; default empty) |
268 | * |
ed6d3334 |
269 | * @return string html formated text area field |
ba556ce5 |
270 | * |
493b168d |
271 | */ |
574240f5 |
272 | function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) { |
ba556ce5 |
273 | |
274 | // no longer accept string arguments for attribs; print |
275 | // backtrace to help people fix their code |
02ded2ae |
276 | //FIXME: throw error instead? |
ba556ce5 |
277 | if (!is_array($aAttribs)) { |
278 | echo '$aAttribs argument to addTextArea() must be an array<br /><pre>'; |
279 | debug_print_backtrace(); |
280 | echo '</pre><br />'; |
281 | exit; |
ed6d3334 |
282 | } |
ba556ce5 |
283 | |
02ded2ae |
284 | // add default css |
ba556ce5 |
285 | else if (!isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea'; |
286 | |
287 | global $oTemplate; |
288 | |
289 | //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); |
290 | $oTemplate->assign('aAttribs', $aAttribs); |
291 | $oTemplate->assign('name', $sName); |
292 | $oTemplate->assign('text', $sText); |
293 | $oTemplate->assign('cols', (int)$iCols); |
294 | $oTemplate->assign('rows', (int)$iRows); |
295 | |
296 | return $oTemplate->fetch('textarea.tpl'); |
493b168d |
297 | } |
298 | |
299 | /** |
300 | * Make a <form> start-tag. |
ba556ce5 |
301 | * |
302 | * @param string $sAction form handler URL |
303 | * @param string $sMethod http method used to submit form data. 'get' or 'post' |
304 | * @param string $sName form name used for identification (used for backward |
305 | * compatibility). Use of id is recommended instead. |
574240f5 |
306 | * @param string $sEnctype content type that is used to submit data. html 4.01 |
ba556ce5 |
307 | * defaults to 'application/x-www-form-urlencoded'. Form |
308 | * with file field needs 'multipart/form-data' encoding type. |
574240f5 |
309 | * @param string $sCharset charset that is used for submitted data |
ba556ce5 |
310 | * @param array $aAttribs (since 1.5.1) extra attributes |
311 | * |
ed6d3334 |
312 | * @return string html formated form start string |
ba556ce5 |
313 | * |
493b168d |
314 | */ |
574240f5 |
315 | function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) { |
574240f5 |
316 | |
ba556ce5 |
317 | global $oTemplate; |
574240f5 |
318 | |
ba556ce5 |
319 | //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); |
320 | $oTemplate->assign('aAttribs', $aAttribs); |
321 | $oTemplate->assign('name', $sName); |
322 | $oTemplate->assign('method', $sMethod); |
323 | $oTemplate->assign('action', $sAction); |
324 | $oTemplate->assign('enctype', $sEnctype); |
325 | $oTemplate->assign('charset', $sCharset); |
493b168d |
326 | |
ba556ce5 |
327 | return $oTemplate->fetch('form.tpl'); |
493b168d |
328 | } |
ba556ce5 |
329 | |