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'])) {
53 $aAttribs['id'] = $aAttribs['name'];
55 // create attribute string (do we have to sanitize keys?)
56 foreach ($aAttribs as $key => $value) {
57 $sAttribs.= ' ' . $key . (! is_null($value) ?
'="'.htmlspecialchars($value).'"':'');
59 return '<input type="'.$sType.'"'.$sAttribs." />\n";
63 * Password input field
64 * @param string $sName field name
65 * @param string $sValue initial password value
66 * @param array $aAttribs (since 1.5.1) extra attributes
67 * @return string html formated password field
69 function addPwField($sName, $sValue = null, $aAttribs=array()) {
70 $aAttribs['name'] = $sName;
71 $aAttribs['value'] = (! is_null($sValue) ?
$sValue : '');
73 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmpwfield';
74 return addInputField('password',$aAttribs);
79 * @param string $sName field name
80 * @param boolean $bChecked controls if field is checked
81 * @param string $sValue
82 * @param array $aAttribs (since 1.5.1) extra attributes
83 * @return string html formated checkbox field
85 function addCheckBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
86 $aAttribs['name'] = $sName;
87 if ($bChecked) $aAttribs['checked'] = 'checked';
88 if (! is_null($sValue)) $aAttribs['value'] = $sValue;
90 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox';
91 return addInputField('checkbox',$aAttribs);
96 * @param string $sName field name
97 * @param boolean $bChecked controls if field is selected
98 * @param string $sValue
99 * @param array $aAttribs (since 1.5.1) extra attributes.
100 * @return string html formated radio box
102 function addRadioBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
103 $aAttribs['name'] = $sName;
104 if ($bChecked) $aAttribs['checked'] = 'checked';
105 if (! is_null($sValue)) $aAttribs['value'] = $sValue;
106 if (! isset($aAttribs['id'])) $aAttribs['id'] = $sName . $sValue;
108 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox';
109 return addInputField('radio', $aAttribs);
113 * A hidden form field.
114 * @param string $sName field name
115 * @param string $sValue field value
116 * @param array $aAttribs (since 1.5.1) extra attributes
117 * @return html formated hidden form field
119 function addHidden($sName, $sValue, $aAttribs=array()) {
120 $aAttribs['name'] = $sName;
121 $aAttribs['value'] = $sValue;
123 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmhiddenfield';
124 return addInputField('hidden', $aAttribs);
129 * @param string $sName field name
130 * @param string $sValue initial field value
131 * @param integer $iSize field size (number of characters)
132 * @param integer $iMaxlength maximum number of characters the user may enter
133 * @param array $aAttribs (since 1.5.1) extra attributes - should be given
134 * in the form array('attribute_name' => 'attribute_value', ...)
135 * @return string html formated text input field
137 function addInput($sName, $sValue = '', $iSize = 0, $iMaxlength = 0, $aAttribs=array()) {
138 $aAttribs['name'] = $sName;
139 $aAttribs['value'] = $sValue;
140 if ($iSize) $aAttribs['size'] = (int)$iSize;
141 if ($iMaxlength) $aAttribs['maxlength'] = (int)$iMaxlength;
143 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield';
144 return addInputField('text', $aAttribs);
148 * Function to create a selectlist from an array.
149 * @param string $sName field name
150 * @param array $aValues field values array ( key => value ) -> <option value="key">value</option>
151 * @param mixed $default the key that will be selected
152 * @param boolean $bUsekeys use the keys of the array as option value or not
153 * @param array $aAttribs (since 1.5.1) extra attributes
154 * @return string html formated selection box
155 * @todo add attributes argument for option tags and default css
157 function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array()) {
159 if(count($aValues) == 1) {
160 $k = key($aValues); $v = array_pop($aValues);
161 return addHidden($sName, ($bUsekeys ?
$k:$v), $aAttribs).
162 htmlspecialchars($v) . "\n";
165 if (isset($aAttribs['id'])) {
166 $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
167 $label_close = '</label>';
173 // create attribute string for select tag
175 foreach ($aAttribs as $key => $value) {
176 $sAttribs.= ' ' . $key . (! is_null($value) ?
'="'.htmlspecialchars($value).'"':'');
179 $ret = '<select name="'.htmlspecialchars($sName) . '"' . $sAttribs . ">\n";
180 foreach ($aValues as $k => $v) {
181 if(!$bUsekeys) $k = $v;
182 $ret .= '<option value="' .
183 htmlspecialchars( $k ) . '"' .
184 (($default == $k) ?
' selected="selected"' : '') .
185 '>' . $label_open . htmlspecialchars($v) . $label_close ."</option>\n";
187 $ret .= "</select>\n";
193 * Form submission button
194 * Note the switched value/name parameters!
195 * @param string $sValue button name
196 * @param string $sName submitted key name
197 * @param array $aAttribs (since 1.5.1) extra attributes
198 * @return string html formated submit input field
200 function addSubmit($sValue, $sName = null, $aAttribs=array()) {
201 $aAttribs['value'] = $sValue;
202 if (! is_null($sName)) $aAttribs['name'] = $sName;
204 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
205 return addInputField('submit', $aAttribs);
209 * @param string $sValue button name
210 * @param array $aAttribs (since 1.5.1) extra attributes
211 * @return string html formated reset input field
213 function addReset($sValue, $aAttribs=array()) {
214 $aAttribs['value'] = $sValue;
216 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield';
217 return addInputField('reset', $aAttribs);
221 * Textarea form element.
222 * @param string $sName field name
223 * @param string $sText initial field value
224 * @param integer $iCols field width (number of chars)
225 * @param integer $iRows field height (number of character rows)
226 * @param array $aAttribs (since 1.5.1) extra attributes. function accepts string argument
227 * for backward compatibility.
228 * @return string html formated text area field
230 function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) {
233 if (is_array($aAttribs)) {
234 // maybe id can default to name?
235 if (isset($aAttribs['id'])) {
236 $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
237 $label_close = '</label>';
240 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea';
241 // create attribute string (do we have to sanitize keys?)
243 foreach ($aAttribs as $key => $value) {
244 $sAttribs.= ' ' . $key . (! is_null($value) ?
'="'.htmlspecialchars($value).'"':'');
246 } elseif (is_string($aAttribs)) {
247 // backward compatibility mode. deprecated.
248 $sAttribs = ' ' . $aAttribs;
252 return '<textarea name="'.htmlspecialchars($sName).'" '.
253 'rows="'.(int)$iRows .'" cols="'.(int)$iCols.'"'.
254 $sAttribs . '>'. $label_open . htmlspecialchars($sText) . $label_close ."</textarea>\n";
258 * Make a <form> start-tag.
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.
263 * @param string $sEnctype content type that is used to submit data. html 4.01
264 * defaults to 'application/x-www-form-urlencoded'. Form with file field needs
265 * 'multipart/form-data' encoding type.
266 * @param string $sCharset charset that is used for submitted data
267 * @param array $aAttribs (since 1.5.1) extra attributes
268 * @return string html formated form start string
270 function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) {
272 if (! isset($aAttribs['id']) && ! empty($sName))
273 $aAttribs['id'] = $sName;
276 $sName = ' name="'.$sName.'"';
279 $sEnctype = ' enctype="'.$sEnctype.'"';
282 $sCharset = ' accept-charset="'.htmlspecialchars($sCharset).'"';
285 // create attribute string (do we have to sanitize keys?)
287 foreach ($aAttribs as $key => $value) {
288 $sAttribs.= ' ' . $key . (! is_null($value) ?
'="'.htmlspecialchars($value).'"':'');
291 return '<form action="'. $sAction .'" method="'. $sMethod .'"'.
292 $sEnctype . $sName . $sCharset . $sAttribs . ">\n";