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