functions/forms.php

   1 <?php
   2
   3 /**
   4  * forms.php - html form functions
   5  *
   6  * Functions to build HTML forms in a safe and consistent manner.
   7  * All attribute values are sanitized with htmlspecialchars().
   8  *
   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.
  12  *
  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.
  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
  27  * @copyright &copy; 2004-2006 The SquirrelMail Project Team
  28  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  29  * @version $Id$
  30  * @package squirrelmail
  31  * @subpackage forms
  32  * @since 1.4.3 and 1.5.1
  33  */
  34
  35 /**
  36  * Helper function to create form fields, not to be called directly,
  37  * only by other functions below.
  38  *
  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
  45  *  lowercase.
  46  * @return string html formated input field
  47  * @deprecated use other functions that provide simple wrappers to this function
  48  */
  49 function 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";
  60 }
  61
  62 /**
  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
  68  */
  69 function 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);
  75 }
  76
  77 /**
  78  * Form checkbox
  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
  84  */
  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;
  89     // add default css
  90     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox';
  91     return addInputField('checkbox',$aAttribs);
  92 }
  93
  94 /**
  95  * Form radio box
  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
 101  */
 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;
 107     // add default css
 108     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox';
 109     return addInputField('radio', $aAttribs);
 110 }
 111
 112 /**
 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
 118  */
 119 function 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);
 125 }
 126
 127 /**
 128  * An input textbox.
 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
 136  */
 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;
 142     // add default css
 143     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield';
 144     return addInputField('text', $aAttribs);
 145 }
 146
 147 /**
 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
 156  */
 157 function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array()) {
 158     // only one element
 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";
 163     }
 164
 165     if (isset($aAttribs['id'])) {
 166         $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
 167         $label_close = '</label>';
 168     } else {
 169         $label_open = '';
 170         $label_close = '';
 171     }
 172
 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;
 182         $ret .= '<option value="' .
 183             htmlspecialchars( $k ) . '"' .
 184             (($default == $k) ? ' selected="selected"' : '') .
 185             '>' . $label_open . htmlspecialchars($v) . $label_close  ."</option>\n";
 186     }
 187     $ret .= "</select>\n";
 188
 189     return $ret;
 190 }
 191
 192 /**
 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
 199  */
 200 function 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);
 206 }
 207 /**
 208  * Form reset button
 209  * @param string $sValue button name
 210  * @param array $aAttribs (since 1.5.1) extra attributes
 211  * @return string html formated reset input field
 212  */
 213 function 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);
 218 }
 219
 220 /**
 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
 229  */
 230 function 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;
 249     } else {
 250         $sAttribs = '';
 251     }
 252     return '<textarea name="'.htmlspecialchars($sName).'" '.
 253         'rows="'.(int)$iRows .'" cols="'.(int)$iCols.'"'.
 254         $sAttribs . '>'. $label_open . htmlspecialchars($sText) . $label_close ."</textarea>\n";
 255 }
 256
 257 /**
 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
 269  */
 270 function 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.'"';
 277     }
 278     if($sEnctype) {
 279         $sEnctype = ' enctype="'.$sEnctype.'"';
 280     }
 281     if($sCharset) {
 282         $sCharset = ' accept-charset="'.htmlspecialchars($sCharset).'"';
 283     }
 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).'"':'');
 289     }
 290
 291     return '<form action="'. $sAction .'" method="'. $sMethod .'"'.
 292         $sEnctype . $sName . $sCharset . $sAttribs . ">\n";
 293 }
 294
 295 ?>