Template files for form widgets being added
[squirrelmail.git] / functions / forms.php
CommitLineData
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 &copy; 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 49function 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 77function 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 93function 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 110function 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 127function 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 145function 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 165function 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
200/**
10ff256e 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 208function 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 221function 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
228/**
493b168d 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 238function 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 278function 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}