Happy New Year
[squirrelmail.git] / functions / forms.php
CommitLineData
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.
3047e291 7 * All attribute values are sanitized with sm_encode_html_special_chars().
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
c4faef33 28 * @copyright 2004-2020 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 50function 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);
3047e291 68//FIXME: all the values in the $aAttribs list used to go thru sm_encode_html_special_chars()... 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] = sm_encode_html_special_chars($value);
ba556ce5 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
3fa09710 79 * @param integer $iSize field size (number of characters)
80 * @param integer $iMaxlength maximum number of characters the user may enter
81 * @param array $aAttribs (since 1.5.1) extra attributes - should be given
82 * in the form array('attribute_name' => 'attribute_value', ...)
83 * @return string html formated password field
10ff256e 84 */
3fa09710 85function addPwField($sName, $sValue = '', $iSize = 0, $iMaxlength = 0, $aAttribs=array()) {
574240f5 86 $aAttribs['name'] = $sName;
3fa09710 87 $aAttribs['value'] = $sValue;
88 if ($iSize) $aAttribs['size'] = (int)$iSize;
89 if ($iMaxlength) $aAttribs['maxlength'] = (int)$iMaxlength;
574240f5 90 // add default css
91 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmpwfield';
92 return addInputField('password',$aAttribs);
10ff256e 93}
94
493b168d 95/**
96 * Form checkbox
574240f5 97 * @param string $sName field name
98 * @param boolean $bChecked controls if field is checked
99 * @param string $sValue
100 * @param array $aAttribs (since 1.5.1) extra attributes
ed6d3334 101 * @return string html formated checkbox field
493b168d 102 */
574240f5 103function addCheckBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
104 $aAttribs['name'] = $sName;
105 if ($bChecked) $aAttribs['checked'] = 'checked';
106 if (! is_null($sValue)) $aAttribs['value'] = $sValue;
107 // add default css
108 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox';
109 return addInputField('checkbox',$aAttribs);
493b168d 110}
111
112/**
113 * Form radio box
574240f5 114 * @param string $sName field name
115 * @param boolean $bChecked controls if field is selected
116 * @param string $sValue
117 * @param array $aAttribs (since 1.5.1) extra attributes.
ed6d3334 118 * @return string html formated radio box
493b168d 119 */
574240f5 120function addRadioBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
121 $aAttribs['name'] = $sName;
122 if ($bChecked) $aAttribs['checked'] = 'checked';
123 if (! is_null($sValue)) $aAttribs['value'] = $sValue;
124 if (! isset($aAttribs['id'])) $aAttribs['id'] = $sName . $sValue;
125 // add default css
126 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox';
127 return addInputField('radio', $aAttribs);
493b168d 128}
129
130/**
131 * A hidden form field.
574240f5 132 * @param string $sName field name
133 * @param string $sValue field value
134 * @param array $aAttribs (since 1.5.1) extra attributes
ed6d3334 135 * @return html formated hidden form field
493b168d 136 */
574240f5 137function addHidden($sName, $sValue, $aAttribs=array()) {
138 $aAttribs['name'] = $sName;
139 $aAttribs['value'] = $sValue;
140 // add default css
141 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmhiddenfield';
142 return addInputField('hidden', $aAttribs);
493b168d 143}
144
145/**
146 * An input textbox.
574240f5 147 * @param string $sName field name
148 * @param string $sValue initial field value
149 * @param integer $iSize field size (number of characters)
150 * @param integer $iMaxlength maximum number of characters the user may enter
87745b9c 151 * @param array $aAttribs (since 1.5.1) extra attributes - should be given
152 * in the form array('attribute_name' => 'attribute_value', ...)
ed6d3334 153 * @return string html formated text input field
493b168d 154 */
574240f5 155function addInput($sName, $sValue = '', $iSize = 0, $iMaxlength = 0, $aAttribs=array()) {
156 $aAttribs['name'] = $sName;
157 $aAttribs['value'] = $sValue;
158 if ($iSize) $aAttribs['size'] = (int)$iSize;
159 if ($iMaxlength) $aAttribs['maxlength'] = (int)$iMaxlength;
160 // add default css
161 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield';
162 return addInputField('text', $aAttribs);
493b168d 163}
164
493b168d 165/**
166 * Function to create a selectlist from an array.
42b7c9d4 167 * @param string $sName Field name
168 * @param array $aValues Field values array(key => value) results in:
169 * <option value="key">value</option>,
170 * although if $bUsekeys is FALSE, then it changes to:
171 * <option value="value">value</option>
172 * @param mixed $default The key(s) that will be selected (it is OK to pass
173 * in an array here in the case of multiple select lists)
174 * @param boolean $bUsekeys Use the keys of the array as option value or not
175 * @param array $aAttribs (since 1.5.1) Extra attributes
176 * @param boolean $bMultiple When TRUE, a multiple select list will be shown
177 * (OPTIONAL; default is FALSE (single select list))
38d93650 178 * @param int $iSize Desired height of multiple select boxes
179 * (OPTIONAL; default is SMOPT_SIZE_NORMAL)
180 * (only applicable when $bMultiple is TRUE)
02ded2ae 181 *
ed6d3334 182 * @return string html formated selection box
574240f5 183 * @todo add attributes argument for option tags and default css
493b168d 184 */
38d93650 185function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array(), $bMultiple = FALSE, $iSize = SMOPT_SIZE_NORMAL) {
493b168d 186 // only one element
38d93650 187 if (!$bMultiple && count($aValues) == 1) {
574240f5 188 $k = key($aValues); $v = array_pop($aValues);
38d93650 189 return addHidden($sName, ($bUsekeys ? $k : $v), $aAttribs)
3047e291 190 . sm_encode_html_special_chars($v);
493b168d 191 }
192
a54c0e78 193 if (! isset($aAttribs['id'])) $aAttribs['id'] = $sName;
42b7c9d4 194
195 // make sure $default is an array, since multiple select lists
196 // need the chance to have more than one default...
197 //
198 if (!is_array($default))
199 $default = array($default);
200
201
ba556ce5 202 global $oTemplate;
ed6d3334 203
3047e291 204//FIXME: all the values in the $aAttribs list and $sName and both the keys and values in $aValues used to go thru sm_encode_html_special_chars()... 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] = sm_encode_html_special_chars($value); $sName = sm_encode_html_special_chars($sName); $aNewValues = array(); foreach ($aValues as $key => $value) $aNewValues[sm_encode_html_special_chars($key)] = sm_encode_html_special_chars($value); $aValues = $aNewValues; And probably this too because it has to be matched to a value that has already been sanitized: $default = sm_encode_html_special_chars($default); (oops, watch out for when $default is an array! (multiple select lists))
ba556ce5 205 $oTemplate->assign('aAttribs', $aAttribs);
206 $oTemplate->assign('aValues', $aValues);
207 $oTemplate->assign('bUsekeys', $bUsekeys);
208 $oTemplate->assign('default', $default);
209 $oTemplate->assign('name', $sName);
42b7c9d4 210 $oTemplate->assign('multiple', $bMultiple);
38d93650 211 $oTemplate->assign('size', $iSize);
574240f5 212
ba556ce5 213 return $oTemplate->fetch('select.tpl');
493b168d 214}
215
216/**
02ded2ae 217 * Normal button
218 *
219 * Note the switched value/name parameters!
220 * Note also that regular buttons are not very useful unless
221 * used with onclick handlers, thus are only really appropriate
222 * if you use them after having checked if JavaScript is turned
223 * on by doing this: if (checkForJavascript()) ...
224 *
225 * @param string $sValue button name
226 * @param string $sName key name
227 * @param array $aAttribs extra attributes
228 *
229 * @return string html formated submit input field
230 *
231 * @since 1.5.2
232 */
233function addButton($sValue, $sName = null, $aAttribs=array()) {
234 $aAttribs['value'] = $sValue;
235 if (! is_null($sName)) $aAttribs['name'] = $sName;
236 // add default css
237 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
238 return addInputField('button', $aAttribs);
239}
240
241/**
10ff256e 242 * Form submission button
243 * Note the switched value/name parameters!
574240f5 244 * @param string $sValue button name
245 * @param string $sName submitted key name
246 * @param array $aAttribs (since 1.5.1) extra attributes
ed6d3334 247 * @return string html formated submit input field
10ff256e 248 */
574240f5 249function addSubmit($sValue, $sName = null, $aAttribs=array()) {
250 $aAttribs['value'] = $sValue;
251 if (! is_null($sName)) $aAttribs['name'] = $sName;
252 // add default css
253 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
254 return addInputField('submit', $aAttribs);
10ff256e 255}
02ded2ae 256
10ff256e 257/**
ed6d3334 258 * Form reset button
574240f5 259 * @param string $sValue button name
260 * @param array $aAttribs (since 1.5.1) extra attributes
ed6d3334 261 * @return string html formated reset input field
10ff256e 262 */
574240f5 263function addReset($sValue, $aAttribs=array()) {
264 $aAttribs['value'] = $sValue;
265 // add default css
266 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield';
267 return addInputField('reset', $aAttribs);
10ff256e 268}
269
270/**
493b168d 271 * Textarea form element.
ba556ce5 272 *
273 * @param string $sName field name
274 * @param string $sText initial field value (OPTIONAL; default empty)
275 * @param integer $iCols field width (number of chars) (OPTIONAL; default 40)
276 * @param integer $iRows field height (number of character rows) (OPTIONAL; default 10)
277 * @param array $aAttribs (since 1.5.1) extra attributes (OPTIONAL; default empty)
278 *
ed6d3334 279 * @return string html formated text area field
ba556ce5 280 *
493b168d 281 */
574240f5 282function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) {
ba556ce5 283
284 // no longer accept string arguments for attribs; print
285 // backtrace to help people fix their code
02ded2ae 286 //FIXME: throw error instead?
ba556ce5 287 if (!is_array($aAttribs)) {
288 echo '$aAttribs argument to addTextArea() must be an array<br /><pre>';
289 debug_print_backtrace();
290 echo '</pre><br />';
291 exit;
ed6d3334 292 }
ba556ce5 293
02ded2ae 294 // add default css
ba556ce5 295 else if (!isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea';
a54c0e78 296
297 if ( empty( $aAttribs['id'] ) ) {
298 $aAttribs['id'] = strtr($sName,'[]','__');
299 }
ba556ce5 300
301 global $oTemplate;
302
3047e291 303//FIXME: all the values in the $aAttribs list as well as $sName and $sText used to go thru sm_encode_html_special_chars()... 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] = sm_encode_html_special_chars($value); $sName = sm_encode_html_special_chars($sName); $sText = sm_encode_html_special_chars($sText);
ba556ce5 304 $oTemplate->assign('aAttribs', $aAttribs);
305 $oTemplate->assign('name', $sName);
306 $oTemplate->assign('text', $sText);
307 $oTemplate->assign('cols', (int)$iCols);
308 $oTemplate->assign('rows', (int)$iRows);
309
310 return $oTemplate->fetch('textarea.tpl');
493b168d 311}
312
313/**
314 * Make a <form> start-tag.
ba556ce5 315 *
199a9ab8 316 * @param string $sAction form handler URL
317 * @param string $sMethod http method used to submit form data. 'get' or 'post'
318 * @param string $sName form name used for identification (used for backward
319 * compatibility). Use of id is recommended instead.
320 * @param string $sEnctype content type that is used to submit data. html 4.01
321 * defaults to 'application/x-www-form-urlencoded'. Form
322 * with file field needs 'multipart/form-data' encoding type.
323 * @param string $sCharset charset that is used for submitted data
324 * @param array $aAttribs (since 1.5.1) extra attributes
325 * @param boolean $bAddToken (since 1.5.2) When given as a string or as boolean TRUE,
326 * a hidden input is also added to the form containing a
327 * security token. When given as TRUE, the input name is
328 * "smtoken"; otherwise the name is the string that is
329 * given for this parameter. When FALSE, no hidden token
330 * input field is added. (OPTIONAL; default not used)
ba556ce5 331 *
ed6d3334 332 * @return string html formated form start string
ba556ce5 333 *
493b168d 334 */
199a9ab8 335function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array(), $bAddToken = FALSE) {
574240f5 336
ba556ce5 337 global $oTemplate;
574240f5 338
3047e291 339//FIXME: all the values in the $aAttribs list as well as $charset used to go thru sm_encode_html_special_chars()... 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] = sm_encode_html_special_chars($value); $sCharset = sm_encode_html_special_chars($sCharset);
ba556ce5 340 $oTemplate->assign('aAttribs', $aAttribs);
341 $oTemplate->assign('name', $sName);
342 $oTemplate->assign('method', $sMethod);
343 $oTemplate->assign('action', $sAction);
344 $oTemplate->assign('enctype', $sEnctype);
345 $oTemplate->assign('charset', $sCharset);
493b168d 346
199a9ab8 347 $sForm = $oTemplate->fetch('form.tpl');
348
349 if ($bAddToken) {
350 $sForm .= addHidden((is_string($bAddToken) ? $bAddToken : 'smtoken'),
351 sm_generate_security_token());
352 }
353
354 return $sForm;
493b168d 355}
ba556ce5 356
61bd57f5 357/**
358 * Creates unique widget names
359 *
360 * Names are formatted as such: "send1", "send2", "send3", etc.,
361 * where "send" in this example is what was given for $base_name
362 *
363 * @param string $base_name The name upon which to base the
364 * returned widget name.
365 * @param boolean $return_count When TRUE, this function will
366 * return the last number used to
367 * create a widget name for $base_name
368 * (OPTIONAL; default = FALSE).
369 *
370 * @return mixed When $return_output is FALSE, a string containing
371 * the unique widget name; otherwise an integer with
372 * the last number used to create the last widget
373 * name for the given $base_name (where 0 (zero) means
374 * that no such widgets have been created yet).
375 *
4709e2f7 376 * @since 1.5.2
61bd57f5 377 *
378 */
379function unique_widget_name($base_name, $return_count=FALSE)
380{
381 static $counts = array();
382
383 if (!isset($counts[$base_name]))
384 $counts[$base_name] = 0;
385
386 if ($return_count)
387 return $counts[$base_name];
388
389 ++$counts[$base_name];
390 return $base_name . $counts[$base_name];
391}
392