moving error message to class constructor function. Prevents
[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'])) {
53 $aAttribs['id'] = $aAttribs['name'];
54 }
55 // create attribute string (do we have to sanitize keys?)
56 foreach ($aAttribs as $key => $value) {
57 $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
58 }
59 return '<input type="'.$sType.'"'.$sAttribs." />\n";
493b168d 60}
61
10ff256e 62/**
63 * Password input field
574240f5 64 * @param string $sName field name
65 * @param string $sValue initial password value
66 * @param array $aAttribs (since 1.5.1) extra attributes
ed6d3334 67 * @return string html formated password field
10ff256e 68 */
574240f5 69function addPwField($sName, $sValue = null, $aAttribs=array()) {
70 $aAttribs['name'] = $sName;
71 $aAttribs['value'] = (! is_null($sValue) ? $sValue : '');
72 // add default css
73 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmpwfield';
74 return addInputField('password',$aAttribs);
10ff256e 75}
76
493b168d 77/**
78 * Form checkbox
574240f5 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
ed6d3334 83 * @return string html formated checkbox field
493b168d 84 */
574240f5 85function 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;
89 // add default css
90 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox';
91 return addInputField('checkbox',$aAttribs);
493b168d 92}
93
94/**
95 * Form radio box
574240f5 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.
ed6d3334 100 * @return string html formated radio box
493b168d 101 */
574240f5 102function 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;
107 // add default css
108 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox';
109 return addInputField('radio', $aAttribs);
493b168d 110}
111
112/**
113 * A hidden form field.
574240f5 114 * @param string $sName field name
115 * @param string $sValue field value
116 * @param array $aAttribs (since 1.5.1) extra attributes
ed6d3334 117 * @return html formated hidden form field
493b168d 118 */
574240f5 119function addHidden($sName, $sValue, $aAttribs=array()) {
120 $aAttribs['name'] = $sName;
121 $aAttribs['value'] = $sValue;
122 // add default css
123 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmhiddenfield';
124 return addInputField('hidden', $aAttribs);
493b168d 125}
126
127/**
128 * An input textbox.
574240f5 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
87745b9c 133 * @param array $aAttribs (since 1.5.1) extra attributes - should be given
134 * in the form array('attribute_name' => 'attribute_value', ...)
ed6d3334 135 * @return string html formated text input field
493b168d 136 */
574240f5 137function 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;
142 // add default css
143 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield';
144 return addInputField('text', $aAttribs);
493b168d 145}
146
493b168d 147/**
148 * Function to create a selectlist from an array.
574240f5 149 * @param string $sName field name
150 * @param array $aValues field values array ( key => value ) -> <option value="key">value</option>
ed6d3334 151 * @param mixed $default the key that will be selected
574240f5 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
ed6d3334 154 * @return string html formated selection box
574240f5 155 * @todo add attributes argument for option tags and default css
493b168d 156 */
574240f5 157function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array()) {
493b168d 158 // only one element
574240f5 159 if(count($aValues) == 1) {
160 $k = key($aValues); $v = array_pop($aValues);
161 return addHidden($sName, ($bUsekeys ? $k:$v), $aAttribs).
745eb9e2 162 htmlspecialchars($v) . "\n";
493b168d 163 }
164
574240f5 165 if (isset($aAttribs['id'])) {
166 $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
ed6d3334 167 $label_close = '</label>';
168 } else {
ed6d3334 169 $label_open = '';
170 $label_close = '';
171 }
172
574240f5 173 // create attribute string for select tag
174 $sAttribs = '';
175 foreach ($aAttribs as $key => $value) {
176 $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
177 }
178
179 $ret = '<select name="'.htmlspecialchars($sName) . '"' . $sAttribs . ">\n";
180 foreach ($aValues as $k => $v) {
181 if(!$bUsekeys) $k = $v;
493b168d 182 $ret .= '<option value="' .
745eb9e2 183 htmlspecialchars( $k ) . '"' .
f79fb61d 184 (($default == $k) ? ' selected="selected"' : '') .
ed6d3334 185 '>' . $label_open . htmlspecialchars($v) . $label_close ."</option>\n";
493b168d 186 }
187 $ret .= "</select>\n";
188
189 return $ret;
190}
191
192/**
10ff256e 193 * Form submission button
194 * Note the switched value/name parameters!
574240f5 195 * @param string $sValue button name
196 * @param string $sName submitted key name
197 * @param array $aAttribs (since 1.5.1) extra attributes
ed6d3334 198 * @return string html formated submit input field
10ff256e 199 */
574240f5 200function addSubmit($sValue, $sName = null, $aAttribs=array()) {
201 $aAttribs['value'] = $sValue;
202 if (! is_null($sName)) $aAttribs['name'] = $sName;
203 // add default css
204 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
205 return addInputField('submit', $aAttribs);
10ff256e 206}
207/**
ed6d3334 208 * Form reset button
574240f5 209 * @param string $sValue button name
210 * @param array $aAttribs (since 1.5.1) extra attributes
ed6d3334 211 * @return string html formated reset input field
10ff256e 212 */
574240f5 213function addReset($sValue, $aAttribs=array()) {
214 $aAttribs['value'] = $sValue;
215 // add default css
216 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield';
217 return addInputField('reset', $aAttribs);
10ff256e 218}
219
220/**
493b168d 221 * Textarea form element.
574240f5 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.
ed6d3334 228 * @return string html formated text area field
493b168d 229 */
574240f5 230function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) {
231 $label_open = '';
232 $label_close = '';
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>';
238 }
239 // add default css
240 if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea';
241 // create attribute string (do we have to sanitize keys?)
242 $sAttribs = '';
243 foreach ($aAttribs as $key => $value) {
244 $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
245 }
246 } elseif (is_string($aAttribs)) {
247 // backward compatibility mode. deprecated.
248 $sAttribs = ' ' . $aAttribs;
ed6d3334 249 } else {
574240f5 250 $sAttribs = '';
ed6d3334 251 }
574240f5 252 return '<textarea name="'.htmlspecialchars($sName).'" '.
253 'rows="'.(int)$iRows .'" cols="'.(int)$iCols.'"'.
254 $sAttribs . '>'. $label_open . htmlspecialchars($sText) . $label_close ."</textarea>\n";
493b168d 255}
256
257/**
258 * Make a <form> start-tag.
574240f5 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
ed6d3334 262 * compatibility). Use of id is recommended.
574240f5 263 * @param string $sEnctype content type that is used to submit data. html 4.01
ed6d3334 264 * defaults to 'application/x-www-form-urlencoded'. Form with file field needs
265 * 'multipart/form-data' encoding type.
574240f5 266 * @param string $sCharset charset that is used for submitted data
267 * @param array $aAttribs (since 1.5.1) extra attributes
ed6d3334 268 * @return string html formated form start string
493b168d 269 */
574240f5 270function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) {
271 // id tags
272 if (! isset($aAttribs['id']) && ! empty($sName))
273 $aAttribs['id'] = $sName;
274
275 if($sName) {
276 $sName = ' name="'.$sName.'"';
493b168d 277 }
574240f5 278 if($sEnctype) {
279 $sEnctype = ' enctype="'.$sEnctype.'"';
493b168d 280 }
574240f5 281 if($sCharset) {
282 $sCharset = ' accept-charset="'.htmlspecialchars($sCharset).'"';
493b168d 283 }
574240f5 284
285 // create attribute string (do we have to sanitize keys?)
286 $sAttribs = '';
287 foreach ($aAttribs as $key => $value) {
288 $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
ed6d3334 289 }
493b168d 290
574240f5 291 return '<form action="'. $sAction .'" method="'. $sMethod .'"'.
292 $sEnctype . $sName . $sCharset . $sAttribs . ">\n";
493b168d 293}
294
4b4abf93 295?>