493b168d |
1 | <?php |
4b4abf93 |
2 | |
493b168d |
3 | /** |
ed6d3334 |
4 | * forms.php - html form functions |
493b168d |
5 | * |
493b168d |
6 | * Functions to build HTML forms in a safe and consistent manner. |
15623730 |
7 | * All attribute values are sanitized with htmlspecialchars(). |
493b168d |
8 | * |
ed6d3334 |
9 | * Currently functions don't provide simple wrappers for file and |
10 | * image input fields, support only submit and reset buttons and use |
15623730 |
11 | * html input tags for buttons. |
ed6d3334 |
12 | * |
574240f5 |
13 | * Since 1.5.1: |
14 | * |
15 | * * 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 | * * input tag functions accept extra html attributes that can be submitted |
20 | * in $aAttribs array. |
21 | * |
22 | * * default css class attributes are added. |
ed6d3334 |
23 | * |
24 | * @link http://www.section508.gov/ Section 508 |
25 | * @link http://www.w3.org/WAI/ Web Accessibility Initiative (WAI) |
26 | * @link http://www.w3.org/TR/html4/ W3.org HTML 4.01 form specs |
47ccfad4 |
27 | * @copyright © 2004-2006 The SquirrelMail Project Team |
4b4abf93 |
28 | * @license http://opensource.org/licenses/gpl-license.php GNU Public License |
74f5d33f |
29 | * @version $Id$ |
493b168d |
30 | * @package squirrelmail |
74f5d33f |
31 | * @subpackage forms |
ed6d3334 |
32 | * @since 1.4.3 and 1.5.1 |
493b168d |
33 | */ |
34 | |
35 | /** |
36 | * Helper function to create form fields, not to be called directly, |
37 | * only by other functions below. |
574240f5 |
38 | * |
39 | * Function used different syntax before 1.5.1 |
40 | * @param string $sType type of input field. Possible values (html 4.01 |
ed6d3334 |
41 | * specs.): text, password, checkbox, radio, submit, reset, file, |
42 | * hidden, image, button. |
574240f5 |
43 | * @param array $aAttribs (since 1.5.1) extra attributes. Array key is |
44 | * attribute name, array value is attribute value. Array keys must use |
45 | * lowercase. |
ed6d3334 |
46 | * @return string html formated input field |
47 | * @deprecated use other functions that provide simple wrappers to this function |
493b168d |
48 | */ |
574240f5 |
49 | function addInputField($sType, $aAttribs=array()) { |
50 | $sAttribs = ''; |
51 | // define unique identifier |
52 | if (! isset($aAttribs['id']) && isset($aAttribs['name']) && ! is_null($aAttribs['name'])) { |
5f817a0b |
53 | /** |
54 | * if 'id' is not set, set it to 'name' and replace brackets |
55 | * with underscores. 'name' might contain field name with squire |
56 | * brackets (array). Brackets are not allowed in id (validator.w3.org |
57 | * fails to validate document). According to html 4.01 manual cdata |
58 | * type description, 'name' attribute uses same type, but validator.w3.org |
59 | * does not barf on brackets in 'name' attributes. |
60 | */ |
61 | $aAttribs['id'] = strtr($aAttribs['name'],'[]','__'); |
574240f5 |
62 | } |
63 | // create attribute string (do we have to sanitize keys?) |
64 | foreach ($aAttribs as $key => $value) { |
65 | $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':''); |
66 | } |
67 | return '<input type="'.$sType.'"'.$sAttribs." />\n"; |
493b168d |
68 | } |
69 | |
10ff256e |
70 | /** |
71 | * Password input field |
574240f5 |
72 | * @param string $sName field name |
73 | * @param string $sValue initial password value |
74 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
75 | * @return string html formated password field |
10ff256e |
76 | */ |
574240f5 |
77 | function addPwField($sName, $sValue = null, $aAttribs=array()) { |
78 | $aAttribs['name'] = $sName; |
79 | $aAttribs['value'] = (! is_null($sValue) ? $sValue : ''); |
80 | // add default css |
81 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmpwfield'; |
82 | return addInputField('password',$aAttribs); |
10ff256e |
83 | } |
84 | |
493b168d |
85 | /** |
86 | * Form checkbox |
574240f5 |
87 | * @param string $sName field name |
88 | * @param boolean $bChecked controls if field is checked |
89 | * @param string $sValue |
90 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
91 | * @return string html formated checkbox field |
493b168d |
92 | */ |
574240f5 |
93 | function addCheckBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) { |
94 | $aAttribs['name'] = $sName; |
95 | if ($bChecked) $aAttribs['checked'] = 'checked'; |
96 | if (! is_null($sValue)) $aAttribs['value'] = $sValue; |
97 | // add default css |
98 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox'; |
99 | return addInputField('checkbox',$aAttribs); |
493b168d |
100 | } |
101 | |
102 | /** |
103 | * Form radio box |
574240f5 |
104 | * @param string $sName field name |
105 | * @param boolean $bChecked controls if field is selected |
106 | * @param string $sValue |
107 | * @param array $aAttribs (since 1.5.1) extra attributes. |
ed6d3334 |
108 | * @return string html formated radio box |
493b168d |
109 | */ |
574240f5 |
110 | function addRadioBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) { |
111 | $aAttribs['name'] = $sName; |
112 | if ($bChecked) $aAttribs['checked'] = 'checked'; |
113 | if (! is_null($sValue)) $aAttribs['value'] = $sValue; |
114 | if (! isset($aAttribs['id'])) $aAttribs['id'] = $sName . $sValue; |
115 | // add default css |
116 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox'; |
117 | return addInputField('radio', $aAttribs); |
493b168d |
118 | } |
119 | |
120 | /** |
121 | * A hidden form field. |
574240f5 |
122 | * @param string $sName field name |
123 | * @param string $sValue field value |
124 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
125 | * @return html formated hidden form field |
493b168d |
126 | */ |
574240f5 |
127 | function addHidden($sName, $sValue, $aAttribs=array()) { |
128 | $aAttribs['name'] = $sName; |
129 | $aAttribs['value'] = $sValue; |
130 | // add default css |
131 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmhiddenfield'; |
132 | return addInputField('hidden', $aAttribs); |
493b168d |
133 | } |
134 | |
135 | /** |
136 | * An input textbox. |
574240f5 |
137 | * @param string $sName field name |
138 | * @param string $sValue initial field value |
139 | * @param integer $iSize field size (number of characters) |
140 | * @param integer $iMaxlength maximum number of characters the user may enter |
87745b9c |
141 | * @param array $aAttribs (since 1.5.1) extra attributes - should be given |
142 | * in the form array('attribute_name' => 'attribute_value', ...) |
ed6d3334 |
143 | * @return string html formated text input field |
493b168d |
144 | */ |
574240f5 |
145 | function addInput($sName, $sValue = '', $iSize = 0, $iMaxlength = 0, $aAttribs=array()) { |
146 | $aAttribs['name'] = $sName; |
147 | $aAttribs['value'] = $sValue; |
148 | if ($iSize) $aAttribs['size'] = (int)$iSize; |
149 | if ($iMaxlength) $aAttribs['maxlength'] = (int)$iMaxlength; |
150 | // add default css |
151 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield'; |
152 | return addInputField('text', $aAttribs); |
493b168d |
153 | } |
154 | |
493b168d |
155 | /** |
156 | * Function to create a selectlist from an array. |
574240f5 |
157 | * @param string $sName field name |
158 | * @param array $aValues field values array ( key => value ) -> <option value="key">value</option> |
ed6d3334 |
159 | * @param mixed $default the key that will be selected |
574240f5 |
160 | * @param boolean $bUsekeys use the keys of the array as option value or not |
161 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
162 | * @return string html formated selection box |
574240f5 |
163 | * @todo add attributes argument for option tags and default css |
493b168d |
164 | */ |
574240f5 |
165 | function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array()) { |
493b168d |
166 | // only one element |
574240f5 |
167 | if(count($aValues) == 1) { |
168 | $k = key($aValues); $v = array_pop($aValues); |
169 | return addHidden($sName, ($bUsekeys ? $k:$v), $aAttribs). |
745eb9e2 |
170 | htmlspecialchars($v) . "\n"; |
493b168d |
171 | } |
172 | |
574240f5 |
173 | if (isset($aAttribs['id'])) { |
174 | $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">'; |
ed6d3334 |
175 | $label_close = '</label>'; |
176 | } else { |
ed6d3334 |
177 | $label_open = ''; |
178 | $label_close = ''; |
179 | } |
180 | |
574240f5 |
181 | // create attribute string for select tag |
182 | $sAttribs = ''; |
183 | foreach ($aAttribs as $key => $value) { |
184 | $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':''); |
185 | } |
186 | |
187 | $ret = '<select name="'.htmlspecialchars($sName) . '"' . $sAttribs . ">\n"; |
188 | foreach ($aValues as $k => $v) { |
189 | if(!$bUsekeys) $k = $v; |
493b168d |
190 | $ret .= '<option value="' . |
745eb9e2 |
191 | htmlspecialchars( $k ) . '"' . |
f79fb61d |
192 | (($default == $k) ? ' selected="selected"' : '') . |
ed6d3334 |
193 | '>' . $label_open . htmlspecialchars($v) . $label_close ."</option>\n"; |
493b168d |
194 | } |
195 | $ret .= "</select>\n"; |
196 | |
197 | return $ret; |
198 | } |
199 | |
10ff256e |
200 | /** |
201 | * Form submission button |
202 | * Note the switched value/name parameters! |
574240f5 |
203 | * @param string $sValue button name |
204 | * @param string $sName submitted key name |
205 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
206 | * @return string html formated submit input field |
10ff256e |
207 | */ |
574240f5 |
208 | function addSubmit($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('submit', $aAttribs); |
10ff256e |
214 | } |
215 | /** |
ed6d3334 |
216 | * Form reset button |
574240f5 |
217 | * @param string $sValue button name |
218 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
219 | * @return string html formated reset input field |
10ff256e |
220 | */ |
574240f5 |
221 | function addReset($sValue, $aAttribs=array()) { |
222 | $aAttribs['value'] = $sValue; |
223 | // add default css |
224 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield'; |
225 | return addInputField('reset', $aAttribs); |
10ff256e |
226 | } |
227 | |
493b168d |
228 | /** |
229 | * Textarea form element. |
574240f5 |
230 | * @param string $sName field name |
231 | * @param string $sText initial field value |
232 | * @param integer $iCols field width (number of chars) |
233 | * @param integer $iRows field height (number of character rows) |
234 | * @param array $aAttribs (since 1.5.1) extra attributes. function accepts string argument |
235 | * for backward compatibility. |
ed6d3334 |
236 | * @return string html formated text area field |
493b168d |
237 | */ |
574240f5 |
238 | function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) { |
239 | $label_open = ''; |
240 | $label_close = ''; |
241 | if (is_array($aAttribs)) { |
242 | // maybe id can default to name? |
243 | if (isset($aAttribs['id'])) { |
244 | $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">'; |
245 | $label_close = '</label>'; |
246 | } |
247 | // add default css |
248 | if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea'; |
249 | // create attribute string (do we have to sanitize keys?) |
250 | $sAttribs = ''; |
251 | foreach ($aAttribs as $key => $value) { |
252 | $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':''); |
253 | } |
254 | } elseif (is_string($aAttribs)) { |
255 | // backward compatibility mode. deprecated. |
256 | $sAttribs = ' ' . $aAttribs; |
ed6d3334 |
257 | } else { |
574240f5 |
258 | $sAttribs = ''; |
ed6d3334 |
259 | } |
574240f5 |
260 | return '<textarea name="'.htmlspecialchars($sName).'" '. |
261 | 'rows="'.(int)$iRows .'" cols="'.(int)$iCols.'"'. |
262 | $sAttribs . '>'. $label_open . htmlspecialchars($sText) . $label_close ."</textarea>\n"; |
493b168d |
263 | } |
264 | |
265 | /** |
266 | * Make a <form> start-tag. |
574240f5 |
267 | * @param string $sAction form handler URL |
268 | * @param string $sMethod http method used to submit form data. 'get' or 'post' |
269 | * @param string $sName form name used for identification (used for backward |
ed6d3334 |
270 | * compatibility). Use of id is recommended. |
574240f5 |
271 | * @param string $sEnctype content type that is used to submit data. html 4.01 |
ed6d3334 |
272 | * defaults to 'application/x-www-form-urlencoded'. Form with file field needs |
273 | * 'multipart/form-data' encoding type. |
574240f5 |
274 | * @param string $sCharset charset that is used for submitted data |
275 | * @param array $aAttribs (since 1.5.1) extra attributes |
ed6d3334 |
276 | * @return string html formated form start string |
493b168d |
277 | */ |
574240f5 |
278 | function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) { |
279 | // id tags |
280 | if (! isset($aAttribs['id']) && ! empty($sName)) |
281 | $aAttribs['id'] = $sName; |
282 | |
283 | if($sName) { |
284 | $sName = ' name="'.$sName.'"'; |
493b168d |
285 | } |
574240f5 |
286 | if($sEnctype) { |
287 | $sEnctype = ' enctype="'.$sEnctype.'"'; |
493b168d |
288 | } |
574240f5 |
289 | if($sCharset) { |
290 | $sCharset = ' accept-charset="'.htmlspecialchars($sCharset).'"'; |
493b168d |
291 | } |
574240f5 |
292 | |
293 | // create attribute string (do we have to sanitize keys?) |
294 | $sAttribs = ''; |
295 | foreach ($aAttribs as $key => $value) { |
296 | $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':''); |
ed6d3334 |
297 | } |
493b168d |
298 | |
574240f5 |
299 | return '<form action="'. $sAction .'" method="'. $sMethod .'"'. |
300 | $sEnctype . $sName . $sCharset . $sAttribs . ">\n"; |
493b168d |
301 | } |