4 * forms.php - html form functions
6 * Functions to build HTML forms in a safe and consistent manner.
7 * All attribute values are sanitized with htmlspecialchars().
9 * Currently functions don't provide simple wrappers for file and
10 * image input fields, support only submit and reset buttons and use
11 * html input tags for buttons.
15 * * all form functions should support id tags. Original
16 * idea by dugan <at> passwall.com. Tags can be used for Section 508
19 * * input tag functions accept extra html attributes that can be submitted
22 * * default css class attributes are added.
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
27 * @copyright © 2004-2006 The SquirrelMail Project Team
28 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
30 * @package squirrelmail
32 * @since 1.4.3 and 1.5.1
36 * Helper function to create form fields, not to be called directly,
37 * only by other functions below.
39 * Function used different syntax before 1.5.1
40 * @param string $sType type of input field. Possible values (html 4.01
41 * specs.): text, password, checkbox, radio, submit, reset, file,
42 * hidden, image, button.
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
46 * @return string html formated input field
47 * @deprecated use other functions that provide simple wrappers to this function
49 function addInputField($sType, $aAttribs=array()) {
51 // define unique identifier
52 if (! isset($aAttribs['id']) && isset($aAttribs['name']) && ! is_null($aAttribs['name'])) {
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.
61 $aAttribs['id'] = strtr($aAttribs['name'],'[]','__');
63 // create attribute string (do we have to sanitize keys?)
64 foreach ($aAttribs as $key => $value) {
65 $sAttribs.= ' ' . $key . (! is_null($value) ?
'="'.htmlspecialchars($value).'"':'');
67 return '<input type="'.$sType.'"'.$sAttribs." />\n";
71 * Password input field
72 * @param string $sName field name
73 * @param string $sValue initial password value
74 * @param array $aAttribs (since 1.5.1) extra attributes
75 * @return string html formated password field
77 function addPwField($sName, $sValue = null, $aAttribs=array()) {
78 $aAttribs['name'] = $sName;
79 $aAttribs['value'] = (! is_null($sValue) ?
$sValue : '');
81 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmpwfield';
82 return addInputField('password',$aAttribs);
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
91 * @return string html formated checkbox field
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;
98 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox';
99 return addInputField('checkbox',$aAttribs);
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.
108 * @return string html formated radio box
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;
116 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox';
117 return addInputField('radio', $aAttribs);
121 * A hidden form field.
122 * @param string $sName field name
123 * @param string $sValue field value
124 * @param array $aAttribs (since 1.5.1) extra attributes
125 * @return html formated hidden form field
127 function addHidden($sName, $sValue, $aAttribs=array()) {
128 $aAttribs['name'] = $sName;
129 $aAttribs['value'] = $sValue;
131 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmhiddenfield';
132 return addInputField('hidden', $aAttribs);
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
141 * @param array $aAttribs (since 1.5.1) extra attributes - should be given
142 * in the form array('attribute_name' => 'attribute_value', ...)
143 * @return string html formated text input field
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;
151 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield';
152 return addInputField('text', $aAttribs);
156 * Function to create a selectlist from an array.
157 * @param string $sName field name
158 * @param array $aValues field values array ( key => value ) -> <option value="key">value</option>
159 * @param mixed $default the key that will be selected
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
162 * @return string html formated selection box
163 * @todo add attributes argument for option tags and default css
165 function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array()) {
167 if(count($aValues) == 1) {
168 $k = key($aValues); $v = array_pop($aValues);
169 return addHidden($sName, ($bUsekeys ?
$k:$v), $aAttribs).
170 htmlspecialchars($v) . "\n";
173 if (isset($aAttribs['id'])) {
174 $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
175 $label_close = '</label>';
181 // create attribute string for select tag
183 foreach ($aAttribs as $key => $value) {
184 $sAttribs.= ' ' . $key . (! is_null($value) ?
'="'.htmlspecialchars($value).'"':'');
187 $ret = '<select name="'.htmlspecialchars($sName) . '"' . $sAttribs . ">\n";
188 foreach ($aValues as $k => $v) {
189 if(!$bUsekeys) $k = $v;
190 $ret .= '<option value="' .
191 htmlspecialchars( $k ) . '"' .
192 (($default == $k) ?
' selected="selected"' : '') .
193 '>' . $label_open . htmlspecialchars($v) . $label_close ."</option>\n";
195 $ret .= "</select>\n";
201 * Form submission button
202 * Note the switched value/name parameters!
203 * @param string $sValue button name
204 * @param string $sName submitted key name
205 * @param array $aAttribs (since 1.5.1) extra attributes
206 * @return string html formated submit input field
208 function addSubmit($sValue, $sName = null, $aAttribs=array()) {
209 $aAttribs['value'] = $sValue;
210 if (! is_null($sName)) $aAttribs['name'] = $sName;
212 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
213 return addInputField('submit', $aAttribs);
217 * @param string $sValue button name
218 * @param array $aAttribs (since 1.5.1) extra attributes
219 * @return string html formated reset input field
221 function addReset($sValue, $aAttribs=array()) {
222 $aAttribs['value'] = $sValue;
224 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield';
225 return addInputField('reset', $aAttribs);
229 * Textarea form element.
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.
236 * @return string html formated text area field
238 function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) {
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>';
248 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea';
249 // create attribute string (do we have to sanitize keys?)
251 foreach ($aAttribs as $key => $value) {
252 $sAttribs.= ' ' . $key . (! is_null($value) ?
'="'.htmlspecialchars($value).'"':'');
254 } elseif (is_string($aAttribs)) {
255 // backward compatibility mode. deprecated.
256 $sAttribs = ' ' . $aAttribs;
260 return '<textarea name="'.htmlspecialchars($sName).'" '.
261 'rows="'.(int)$iRows .'" cols="'.(int)$iCols.'"'.
262 $sAttribs . '>'. $label_open . htmlspecialchars($sText) . $label_close ."</textarea>\n";
266 * Make a <form> start-tag.
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
270 * compatibility). Use of id is recommended.
271 * @param string $sEnctype content type that is used to submit data. html 4.01
272 * defaults to 'application/x-www-form-urlencoded'. Form with file field needs
273 * 'multipart/form-data' encoding type.
274 * @param string $sCharset charset that is used for submitted data
275 * @param array $aAttribs (since 1.5.1) extra attributes
276 * @return string html formated form start string
278 function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) {
280 if (! isset($aAttribs['id']) && ! empty($sName))
281 $aAttribs['id'] = $sName;
284 $sName = ' name="'.$sName.'"';
287 $sEnctype = ' enctype="'.$sEnctype.'"';
290 $sCharset = ' accept-charset="'.htmlspecialchars($sCharset).'"';
293 // create attribute string (do we have to sanitize keys?)
295 foreach ($aAttribs as $key => $value) {
296 $sAttribs.= ' ' . $key . (! is_null($value) ?
'="'.htmlspecialchars($value).'"':'');
299 return '<form action="'. $sAction .'" method="'. $sMethod .'"'.
300 $sEnctype . $sName . $sCharset . $sAttribs . ">\n";