functions/forms.php

   1 <?php
   2
   3 /**
   4  * forms.php - html form functions
   5  *
   6  * Functions to build forms in a safe and consistent manner.
   7  * All attribute values are sanitized with htmlspecialchars().
   8 //FIXME: I think the Template class might be better place to sanitize inside assign() method
   9  *
  10  * Currently functions don't provide simple wrappers for file and
  11  * image input fields, support only submit and reset buttons and use
  12  * html input tags for buttons.
  13  *
  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.
  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
  28  * @copyright &copy; 2004-2007 The SquirrelMail Project Team
  29  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  30  * @version $Id$
  31  * @package squirrelmail
  32  * @subpackage forms
  33  * @since 1.4.3 and 1.5.1
  34  */
  35
  36 /**
  37  * Helper function to create form fields, not to be called directly,
  38  * only by other functions below.
  39  *
  40  * Function used different syntax before 1.5.1
  41  * @param string $sType type of input field. Possible values (html 4.01
  42  *  specs.): text, password, checkbox, radio, submit, reset, file,
  43  *  hidden, image, button.
  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.
  47  * @return string html formated input field
  48  * @deprecated use other functions that provide simple wrappers to this function
  49  */
  50 function addInputField($sType, $aAttribs=array()) {
  51     $sAttribs = '';
  52     // define unique identifier
  53     if (! isset($aAttribs['id']) && isset($aAttribs['name']) && ! is_null($aAttribs['name'])) {
  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'],'[]','__');
  63     }
  64
  65     global $oTemplate;
  66
  67     $oTemplate->assign('type', $sType);
  68 //FIXME: all the values in the $aAttribs list used to go thru htmlspecialchars()... 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] = htmlspecialchars($value);
  69     $oTemplate->assign('aAttribs', $aAttribs);
  70
  71     return $oTemplate->fetch('input.tpl');
  72
  73 }
  74
  75 /**
  76  * Password input field
  77  * @param string $sName field name
  78  * @param string $sValue initial password value
  79  * @param array $aAttribs (since 1.5.1) extra attributes
  80  * @return string html formated password field
  81  */
  82 function addPwField($sName, $sValue = null, $aAttribs=array()) {
  83     $aAttribs['name']  = $sName;
  84     $aAttribs['value'] = (! is_null($sValue) ? $sValue : '');
  85     // add default css
  86     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmpwfield';
  87     return addInputField('password',$aAttribs);
  88 }
  89
  90 /**
  91  * Form checkbox
  92  * @param string $sName field name
  93  * @param boolean $bChecked controls if field is checked
  94  * @param string $sValue
  95  * @param array $aAttribs (since 1.5.1) extra attributes
  96  * @return string html formated checkbox field
  97  */
  98 function addCheckBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
  99     $aAttribs['name'] = $sName;
 100     if ($bChecked) $aAttribs['checked'] = 'checked';
 101     if (! is_null($sValue)) $aAttribs['value'] = $sValue;
 102     // add default css
 103     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox';
 104     return addInputField('checkbox',$aAttribs);
 105 }
 106
 107 /**
 108  * Form radio box
 109  * @param string $sName field name
 110  * @param boolean $bChecked controls if field is selected
 111  * @param string $sValue
 112  * @param array $aAttribs (since 1.5.1) extra attributes.
 113  * @return string html formated radio box
 114  */
 115 function addRadioBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
 116     $aAttribs['name'] = $sName;
 117     if ($bChecked) $aAttribs['checked'] = 'checked';
 118     if (! is_null($sValue)) $aAttribs['value'] = $sValue;
 119     if (! isset($aAttribs['id'])) $aAttribs['id'] = $sName . $sValue;
 120     // add default css
 121     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox';
 122     return addInputField('radio', $aAttribs);
 123 }
 124
 125 /**
 126  * A hidden form field.
 127  * @param string $sName field name
 128  * @param string $sValue field value
 129  * @param array $aAttribs (since 1.5.1) extra attributes
 130  * @return html formated hidden form field
 131  */
 132 function addHidden($sName, $sValue, $aAttribs=array()) {
 133     $aAttribs['name'] = $sName;
 134     $aAttribs['value'] = $sValue;
 135     // add default css
 136     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmhiddenfield';
 137     return addInputField('hidden', $aAttribs);
 138 }
 139
 140 /**
 141  * An input textbox.
 142  * @param string $sName field name
 143  * @param string $sValue initial field value
 144  * @param integer $iSize field size (number of characters)
 145  * @param integer $iMaxlength maximum number of characters the user may enter
 146  * @param array $aAttribs (since 1.5.1) extra attributes - should be given
 147  *                        in the form array('attribute_name' => 'attribute_value', ...)
 148  * @return string html formated text input field
 149  */
 150 function addInput($sName, $sValue = '', $iSize = 0, $iMaxlength = 0, $aAttribs=array()) {
 151     $aAttribs['name'] = $sName;
 152     $aAttribs['value'] = $sValue;
 153     if ($iSize) $aAttribs['size'] = (int)$iSize;
 154     if ($iMaxlength) $aAttribs['maxlength'] = (int)$iMaxlength;
 155     // add default css
 156     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield';
 157     return addInputField('text', $aAttribs);
 158 }
 159
 160 /**
 161  * Function to create a selectlist from an array.
 162  * @param string  $sName     Field name
 163  * @param array   $aValues   Field values array(key => value) results in:
 164  *                           <option value="key">value</option>,
 165  *                           although if $bUsekeys is FALSE, then it changes to:
 166  *                           <option value="value">value</option>
 167  * @param mixed   $default   The key(s) that will be selected (it is OK to pass
 168  *                           in an array here in the case of multiple select lists)
 169  * @param boolean $bUsekeys  Use the keys of the array as option value or not
 170  * @param array   $aAttribs  (since 1.5.1) Extra attributes
 171  * @param boolean $bMultiple When TRUE, a multiple select list will be shown
 172  *                           (OPTIONAL; default is FALSE (single select list))
 173  * @param int     $iSize     Desired height of multiple select boxes
 174  *                           (OPTIONAL; default is SMOPT_SIZE_NORMAL)
 175  *                           (only applicable when $bMultiple is TRUE)
 176  *
 177  * @return string html formated selection box
 178  * @todo add attributes argument for option tags and default css
 179  */
 180 function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array(), $bMultiple = FALSE, $iSize = SMOPT_SIZE_NORMAL) {
 181     // only one element
 182     if (!$bMultiple && count($aValues) == 1) {
 183         $k = key($aValues); $v = array_pop($aValues);
 184         return addHidden($sName, ($bUsekeys ? $k : $v), $aAttribs)
 185              . htmlspecialchars($v);
 186     }
 187
 188
 189     // make sure $default is an array, since multiple select lists
 190     // need the chance to have more than one default...
 191     //
 192     if (!is_array($default))
 193        $default = array($default);
 194
 195
 196     global $oTemplate;
 197
 198 //FIXME: all the values in the $aAttribs list and $sName and both the keys and values in $aValues used to go thru htmlspecialchars()... 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] = htmlspecialchars($value); $sName = htmlspecialchars($sName); $aNewValues = array(); foreach ($aValues as $key => $value) $aNewValues[htmlspecialchars($key)] = htmlspecialchars($value); $aValues = $aNewValues;   And probably this too because it has to be matched to a value that has already been sanitized: $default = htmlspecialchars($default);  (oops, watch out for when $default is an array! (multiple select lists))
 199     $oTemplate->assign('aAttribs', $aAttribs);
 200     $oTemplate->assign('aValues', $aValues);
 201     $oTemplate->assign('bUsekeys', $bUsekeys);
 202     $oTemplate->assign('default', $default);
 203     $oTemplate->assign('name', $sName);
 204     $oTemplate->assign('multiple', $bMultiple);
 205     $oTemplate->assign('size', $iSize);
 206
 207     return $oTemplate->fetch('select.tpl');
 208 }
 209
 210 /**
 211  * Normal button
 212  *
 213  * Note the switched value/name parameters!
 214  * Note also that regular buttons are not very useful unless
 215  * used with onclick handlers, thus are only really appropriate
 216  * if you use them after having checked if JavaScript is turned
 217  * on by doing this:  if (checkForJavascript()) ...
 218  *
 219  * @param string $sValue button name
 220  * @param string $sName key name
 221  * @param array $aAttribs extra attributes
 222  *
 223  * @return string html formated submit input field
 224  *
 225  * @since 1.5.2
 226  */
 227 function addButton($sValue, $sName = null, $aAttribs=array()) {
 228     $aAttribs['value'] = $sValue;
 229     if (! is_null($sName)) $aAttribs['name'] = $sName;
 230     // add default css
 231     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
 232     return addInputField('button', $aAttribs);
 233 }
 234
 235 /**
 236  * Form submission button
 237  * Note the switched value/name parameters!
 238  * @param string $sValue button name
 239  * @param string $sName submitted key name
 240  * @param array $aAttribs (since 1.5.1) extra attributes
 241  * @return string html formated submit input field
 242  */
 243 function addSubmit($sValue, $sName = null, $aAttribs=array()) {
 244     $aAttribs['value'] = $sValue;
 245     if (! is_null($sName)) $aAttribs['name'] = $sName;
 246     // add default css
 247     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
 248     return addInputField('submit', $aAttribs);
 249 }
 250
 251 /**
 252  * Form reset button
 253  * @param string $sValue button name
 254  * @param array $aAttribs (since 1.5.1) extra attributes
 255  * @return string html formated reset input field
 256  */
 257 function addReset($sValue, $aAttribs=array()) {
 258     $aAttribs['value'] = $sValue;
 259     // add default css
 260     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield';
 261     return addInputField('reset', $aAttribs);
 262 }
 263
 264 /**
 265  * Textarea form element.
 266  *
 267  * @param string  $sName    field name
 268  * @param string  $sText    initial field value (OPTIONAL; default empty)
 269  * @param integer $iCols    field width (number of chars) (OPTIONAL; default 40)
 270  * @param integer $iRows    field height (number of character rows) (OPTIONAL; default 10)
 271  * @param array   $aAttribs (since 1.5.1) extra attributes (OPTIONAL; default empty)
 272  *
 273  * @return string html formated text area field
 274  *
 275  */
 276 function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) {
 277
 278     // no longer accept string arguments for attribs; print
 279     // backtrace to help people fix their code
 280     //FIXME: throw error instead?
 281     if (!is_array($aAttribs)) {
 282         echo '$aAttribs argument to addTextArea() must be an array<br /><pre>';
 283         debug_print_backtrace();
 284         echo '</pre><br />';
 285         exit;
 286     }
 287
 288     // add default css
 289     else if (!isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea';
 290
 291     global $oTemplate;
 292
 293 //FIXME: all the values in the $aAttribs list as well as $sName and $sText used to go thru htmlspecialchars()... 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] = htmlspecialchars($value); $sName = htmlspecialchars($sName); $sText = htmlspecialchars($sText);
 294     $oTemplate->assign('aAttribs', $aAttribs);
 295     $oTemplate->assign('name', $sName);
 296     $oTemplate->assign('text', $sText);
 297     $oTemplate->assign('cols', (int)$iCols);
 298     $oTemplate->assign('rows', (int)$iRows);
 299
 300     return $oTemplate->fetch('textarea.tpl');
 301 }
 302
 303 /**
 304  * Make a <form> start-tag.
 305  *
 306  * @param string $sAction  form handler URL
 307  * @param string $sMethod  http method used to submit form data. 'get' or 'post'
 308  * @param string $sName    form name used for identification (used for backward
 309  *                         compatibility). Use of id is recommended instead.
 310  * @param string $sEnctype content type that is used to submit data. html 4.01
 311  *                         defaults to 'application/x-www-form-urlencoded'. Form
 312  *                         with file field needs 'multipart/form-data' encoding type.
 313  * @param string $sCharset charset that is used for submitted data
 314  * @param array  $aAttribs (since 1.5.1) extra attributes
 315  *
 316  * @return string html formated form start string
 317  *
 318  */
 319 function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) {
 320
 321     global $oTemplate;
 322
 323 //FIXME: all the values in the $aAttribs list as well as $charset used to go thru htmlspecialchars()... 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] = htmlspecialchars($value); $sCharset = htmlspecialchars($sCharset);
 324     $oTemplate->assign('aAttribs', $aAttribs);
 325     $oTemplate->assign('name', $sName);
 326     $oTemplate->assign('method', $sMethod);
 327     $oTemplate->assign('action', $sAction);
 328     $oTemplate->assign('enctype', $sEnctype);
 329     $oTemplate->assign('charset', $sCharset);
 330
 331     return $oTemplate->fetch('form.tpl');
 332 }
 333