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