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 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  * @link http://www.section508.gov/ Section 508
  20  * @link http://www.w3.org/WAI/ Web Accessibility Initiative (WAI)
  21  * @link http://www.w3.org/TR/html4/ W3.org HTML 4.01 form specs
  22  * @version $Id$
  23  * @package squirrelmail
  24  * @subpackage forms
  25  * @since 1.4.3 and 1.5.1
  26  */
  27
  28 /**
  29  * Helper function to create form fields, not to be called directly,
  30  * only by other functions below.
  31  * @param string $type type of input field. Possible values (html 4.01
  32  *  specs.): text, password, checkbox, radio, submit, reset, file,
  33  *  hidden, image, button.
  34  * @param string $name form field name
  35  * @param string $value initial field value
  36  * @param string $attributes extra attributes
  37  * @param string $id (since 1.5.1) assigns unique identifier to an element
  38  * @return string html formated input field
  39  * @deprecated use other functions that provide simple wrappers to this function
  40  */
  41 function addInputField($type, $name = null, $value = null, $attributes = '', $id = null) {
  42     return '<input type="'.$type.'"'.
  43         ($name  !== null ? ' name="'.htmlspecialchars($name).'"'   : '').
  44         ($id  !== null ? ' id="'.htmlspecialchars($id).'"'
  45             : ($name  !== null ? ' id="'.htmlspecialchars($name).'"'   : '')).
  46         ($value !== null ? ' value="'.htmlspecialchars($value).'"' : '').
  47         $attributes . " />\n";
  48 }
  49
  50 /**
  51  * Password input field
  52  * @param string $name field name
  53  * @param string $value initial password value
  54  * @param string $id (since 1.5.1) assigns unique identifier to an element
  55  * @return string html formated password field
  56  */
  57 function addPwField($name , $value = null, $id = null) {
  58     return addInputField('password', $name , $value, '', $id);
  59 }
  60
  61 /**
  62  * Form checkbox
  63  * @param string $name field name
  64  * @param boolean $checked controls if field is checked
  65  * @param string $value
  66  * @param string $xtra (since 1.5.1) extra field attributes
  67  * @param string $id (since 1.5.1) assigns unique identifier to an element
  68  * @return string html formated checkbox field
  69  */
  70 function addCheckBox($name, $checked = false, $value = null, $xtra = '', $id = null) {
  71     return addInputField('checkbox', $name, $value,
  72         ($checked ? ' checked="checked"' : '') . ' ' . $xtra, $id);
  73 }
  74
  75 /**
  76  * Form radio box
  77  * @param string $name field name
  78  * @param boolean $checked controls if field is selected
  79  * @param string $value
  80  * @param string $id (since 1.5.1) assigns unique identifier to an element.
  81  *  Defaults to combined $name and $value string
  82  * @return string html formated radio box
  83  */
  84 function addRadioBox($name, $checked = false, $value = null, $id = '') {
  85     if (empty($id)) {
  86         $id = $name . $value;
  87     }
  88     return addInputField('radio', $name, $value,
  89         ($checked ? ' checked="checked"' : ''), $id);
  90 }
  91
  92 /**
  93  * A hidden form field.
  94  * @param string $name field name
  95  * @param string $value field value
  96  * @param string $id (since 1.5.1) assigns unique identifier to an element
  97  * @return html formated hidden form field
  98  */
  99 function addHidden($name, $value, $id = null) {
 100     return addInputField('hidden', $name, $value, '', $id);
 101 }
 102
 103 /**
 104  * An input textbox.
 105  * @param string $name field name
 106  * @param string $value initial field value
 107  * @param integer $size field size (number of characters)
 108  * @param integer $maxlength maximum number of characters the user may enter
 109  * @param string $id (since 1.5.1) assigns unique identifier to an element
 110  * @return string html formated text input field
 111  */
 112 function addInput($name, $value = '', $size = 0, $maxlength = 0, $id = null) {
 113
 114     $attr = '';
 115     if ($size) {
 116         $attr.= ' size="'.(int)$size.'"';
 117     }
 118     if ($maxlength) {
 119         $attr.= ' maxlength="'.(int)$maxlength .'"';
 120     }
 121
 122     return addInputField('text', $name, $value, $attr, $id);
 123 }
 124
 125 /**
 126  * Function to create a selectlist from an array.
 127  * @param string $name field name
 128  * @param array $values field values array ( key => value )  ->     <option value="key">value</option>
 129  * @param mixed $default the key that will be selected
 130  * @param boolean $usekeys use the keys of the array as option value or not
 131  * @param string $id (since 1.5.1) assigns unique identifier to an element
 132  * @return string html formated selection box
 133  */
 134 function addSelect($name, $values, $default = null, $usekeys = false, $id = null) {
 135     // only one element
 136     if(count($values) == 1) {
 137         $k = key($values); $v = array_pop($values);
 138         return addHidden($name, ($usekeys ? $k:$v), $id).
 139             htmlspecialchars($v) . "\n";
 140     }
 141
 142     if (! is_null($id)) {
 143         $id = ' id="'.htmlspecialchars($id).'"';
 144         $label_open = '<label for="'.htmlspecialchars($id).'">';
 145         $label_close = '</label>';
 146     } else {
 147         $id = '';
 148         $label_open = '';
 149         $label_close = '';
 150     }
 151
 152     $ret = '<select name="'.htmlspecialchars($name) . '"' . $id . ">\n";
 153     foreach ($values as $k => $v) {
 154         if(!$usekeys) $k = $v;
 155         $ret .= '<option value="' .
 156             htmlspecialchars( $k ) . '"' .
 157             (($default == $k) ? ' selected="selected"' : '') .
 158             '>' . $label_open . htmlspecialchars($v) . $label_close  ."</option>\n";
 159     }
 160     $ret .= "</select>\n";
 161
 162     return $ret;
 163 }
 164
 165 /**
 166  * Form submission button
 167  * Note the switched value/name parameters!
 168  * @param string $value button name
 169  * @param string $name submitted key name
 170  * @param string $id (since 1.5.1) assigns unique identifier to an element
 171  * @return string html formated submit input field
 172  */
 173 function addSubmit($value, $name = null, $id = null) {
 174     return addInputField('submit', $name, $value, '', $id);
 175 }
 176 /**
 177  * Form reset button
 178  * @param string $value button name
 179  * @param string $id (since 1.5.1) assigns unique identifier to an element
 180  * @return string html formated reset input field
 181  */
 182 function addReset($value, $id = null) {
 183     return addInputField('reset', null, $value, '', $id);
 184 }
 185
 186 /**
 187  * Textarea form element.
 188  * @param string $name field name
 189  * @param string $text initial field value
 190  * @param integer $cols field width (number of chars)
 191  * @param integer $rows field height (number of character rows)
 192  * @param string $attr extra attributes
 193  * @param string $id (since 1.5.1) assigns unique identifier to an element
 194  * @return string html formated text area field
 195  */
 196 function addTextArea($name, $text = '', $cols = 40, $rows = 10, $attr = '', $id = '') {
 197     if (!empty($id)) {
 198         $id = ' id="'. htmlspecialchars($id) . '"';
 199         $label_open = '<label for="'.htmlspecialchars($id).'">';
 200         $label_close = '</label>';
 201     } else {
 202         $label_open = '';
 203         $label_close = '';
 204     }
 205     return '<textarea name="'.htmlspecialchars($name).'" '.
 206         'rows="'.(int)$rows .'" cols="'.(int)$cols.'" '.
 207         $attr . $id . '>'. $label_open . htmlspecialchars($text) . $label_close ."</textarea>\n";
 208 }
 209
 210 /**
 211  * Make a <form> start-tag.
 212  * @param string $action form handler URL
 213  * @param string $method http method used to submit form data. 'get' or 'post'
 214  * @param string $name form name used for identification (used for backward
 215  *  compatibility). Use of id is recommended.
 216  * @param string $enctype content type that is used to submit data. html 4.01
 217  *  defaults to 'application/x-www-form-urlencoded'. Form with file field needs
 218  *  'multipart/form-data' encoding type.
 219  * @param string $charset charset that is used for submitted data
 220  * @param string $id (since 1.5.1) assigns unique identifier to an element
 221  * @return string html formated form start string
 222  */
 223 function addForm($action, $method = 'post', $name = '', $enctype = '', $charset = '', $id = '') {
 224     if($name) {
 225         $name = ' name="'.$name.'"';
 226     }
 227     if($enctype) {
 228         $enctype = ' enctype="'.$enctype.'"';
 229     }
 230     if($charset) {
 231         $charset = ' accept-charset="'.htmlspecialchars($charset).'"';
 232     }
 233     if (!empty($id)) {
 234         $id = ' id="'.htmlspecialchars($id).'"';
 235     }
 236
 237     return '<form action="'. $action .'" method="'. $method .'"'.
 238         $enctype . $name . $charset . $id . ">\n";
 239 }
 240
 241 ?>