functions/forms.php

   1 <?php
   2 /**
   3  * forms.php - html form functions
   4  *
   5  * Copyright (c) 2004-2005 The SquirrelMail Project Team
   6  * Licensed under the GNU GPL. For full terms see the file COPYING.
   7  *
   8  * Functions to build HTML forms in a safe and consistent manner.
   9  * All attribute values are sanitized with htmlspecialchars().
  10  *
  11  * Currently functions don't provide simple wrappers for file and
  12  * image input fields, support only submit and reset buttons and use
  13  * html input tags for buttons.
  14  *
  15  * Since 1.5.1:
  16  *
  17  *  * all form functions should support id tags. Original
  18  *  idea by dugan <at> passwall.com. Tags can be used for Section 508
  19  *  or WAI compliance.
  20  *
  21  *  * input tag functions accept extra html attributes that can be submitted
  22  *  in $aAttribs array.
  23  *
  24  *  * default css class attributes are added.
  25  *
  26  * @link http://www.section508.gov/ Section 508
  27  * @link http://www.w3.org/WAI/ Web Accessibility Initiative (WAI)
  28  * @link http://www.w3.org/TR/html4/ W3.org HTML 4.01 form specs
  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
 134  * @return string html formated text input field
 135  */
 136 function addInput($sName, $sValue = '', $iSize = 0, $iMaxlength = 0, $aAttribs=array()) {
 137     $aAttribs['name'] = $sName;
 138     $aAttribs['value'] = $sValue;
 139     if ($iSize) $aAttribs['size'] = (int)$iSize;
 140     if ($iMaxlength) $aAttribs['maxlength'] = (int)$iMaxlength;
 141     // add default css
 142     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield';
 143     return addInputField('text', $aAttribs);
 144 }
 145
 146 /**
 147  * Function to create a selectlist from an array.
 148  * @param string $sName field name
 149  * @param array $aValues field values array ( key => value )  ->     <option value="key">value</option>
 150  * @param mixed $default the key that will be selected
 151  * @param boolean $bUsekeys use the keys of the array as option value or not
 152  * @param array $aAttribs (since 1.5.1) extra attributes
 153  * @return string html formated selection box
 154  * @todo add attributes argument for option tags and default css
 155  */
 156 function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array()) {
 157     // only one element
 158     if(count($aValues) == 1) {
 159         $k = key($aValues); $v = array_pop($aValues);
 160         return addHidden($sName, ($bUsekeys ? $k:$v), $aAttribs).
 161             htmlspecialchars($v) . "\n";
 162     }
 163
 164     if (isset($aAttribs['id'])) {
 165         $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
 166         $label_close = '</label>';
 167     } else {
 168         $label_open = '';
 169         $label_close = '';
 170     }
 171
 172     // create attribute string for select tag
 173     $sAttribs = '';
 174     foreach ($aAttribs as $key => $value) {
 175         $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
 176     }
 177
 178     $ret = '<select name="'.htmlspecialchars($sName) . '"' . $sAttribs . ">\n";
 179     foreach ($aValues as $k => $v) {
 180         if(!$bUsekeys) $k = $v;
 181         $ret .= '<option value="' .
 182             htmlspecialchars( $k ) . '"' .
 183             (($default == $k) ? ' selected="selected"' : '') .
 184             '>' . $label_open . htmlspecialchars($v) . $label_close  ."</option>\n";
 185     }
 186     $ret .= "</select>\n";
 187
 188     return $ret;
 189 }
 190
 191 /**
 192  * Form submission button
 193  * Note the switched value/name parameters!
 194  * @param string $sValue button name
 195  * @param string $sName submitted key name
 196  * @param array $aAttribs (since 1.5.1) extra attributes
 197  * @return string html formated submit input field
 198  */
 199 function addSubmit($sValue, $sName = null, $aAttribs=array()) {
 200     $aAttribs['value'] = $sValue;
 201     if (! is_null($sName)) $aAttribs['name'] = $sName;
 202     // add default css
 203     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
 204     return addInputField('submit', $aAttribs);
 205 }
 206 /**
 207  * Form reset button
 208  * @param string $sValue button name
 209  * @param array $aAttribs (since 1.5.1) extra attributes
 210  * @return string html formated reset input field
 211  */
 212 function addReset($sValue, $aAttribs=array()) {
 213     $aAttribs['value'] = $sValue;
 214     // add default css
 215     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield';
 216     return addInputField('reset', $aAttribs);
 217 }
 218
 219 /**
 220  * Textarea form element.
 221  * @param string $sName field name
 222  * @param string $sText initial field value
 223  * @param integer $iCols field width (number of chars)
 224  * @param integer $iRows field height (number of character rows)
 225  * @param array $aAttribs (since 1.5.1) extra attributes. function accepts string argument
 226  * for backward compatibility.
 227  * @return string html formated text area field
 228  */
 229 function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) {
 230     $label_open = '';
 231     $label_close = '';
 232     if (is_array($aAttribs)) {
 233         // maybe id can default to name?
 234         if (isset($aAttribs['id'])) {
 235             $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
 236             $label_close = '</label>';
 237         }
 238         // add default css
 239         if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea';
 240         // create attribute string (do we have to sanitize keys?)
 241         $sAttribs = '';
 242         foreach ($aAttribs as $key => $value) {
 243             $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
 244         }
 245     } elseif (is_string($aAttribs)) {
 246         // backward compatibility mode. deprecated.
 247         $sAttribs = ' ' . $aAttribs;
 248     } else {
 249         $sAttribs = '';
 250     }
 251     return '<textarea name="'.htmlspecialchars($sName).'" '.
 252         'rows="'.(int)$iRows .'" cols="'.(int)$iCols.'"'.
 253         $sAttribs . '>'. $label_open . htmlspecialchars($sText) . $label_close ."</textarea>\n";
 254 }
 255
 256 /**
 257  * Make a <form> start-tag.
 258  * @param string $sAction form handler URL
 259  * @param string $sMethod http method used to submit form data. 'get' or 'post'
 260  * @param string $sName form name used for identification (used for backward
 261  *  compatibility). Use of id is recommended.
 262  * @param string $sEnctype content type that is used to submit data. html 4.01
 263  *  defaults to 'application/x-www-form-urlencoded'. Form with file field needs
 264  *  'multipart/form-data' encoding type.
 265  * @param string $sCharset charset that is used for submitted data
 266  * @param array $aAttribs (since 1.5.1) extra attributes
 267  * @return string html formated form start string
 268  */
 269 function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) {
 270     // id tags
 271     if (! isset($aAttribs['id']) && ! empty($sName))
 272         $aAttribs['id'] = $sName;
 273
 274     if($sName) {
 275         $sName = ' name="'.$sName.'"';
 276     }
 277     if($sEnctype) {
 278         $sEnctype = ' enctype="'.$sEnctype.'"';
 279     }
 280     if($sCharset) {
 281         $sCharset = ' accept-charset="'.htmlspecialchars($sCharset).'"';
 282     }
 283
 284     // create attribute string (do we have to sanitize keys?)
 285     $sAttribs = '';
 286     foreach ($aAttribs as $key => $value) {
 287         $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
 288     }
 289
 290     return '<form action="'. $sAction .'" method="'. $sMethod .'"'.
 291         $sEnctype . $sName . $sCharset . $sAttribs . ">\n";
 292 }
 293
 294 ?>