Source for file forms.php

Documentation is available at 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: forms.php,v 1.24 2006/07/15 12:00:44 tokul Exp $
  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.         /**
  54.          * if 'id' is not set, set it to 'name' and replace brackets 
  55.          * with underscores. 'name' might contain field name with squire
  56.          * brackets (array). Brackets are not allowed in id (validator.w3.org
  57.          * fails to validate document). According to html 4.01 manual cdata 
  58.          * type description, 'name' attribute uses same type, but validator.w3.org 
  59.          * does not barf on brackets in 'name' attributes.
  60.          */
  61.         $aAttribs['id'] = strtr($aAttribs['name'],'[]','__');
  62.     }
  63.     // create attribute string (do we have to sanitize keys?)
  64.     foreach ($aAttribs as $key => $value) {
  65.         $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
  66.     }
  67.     return '<input type="'.$sType.'"'.$sAttribs." />\n";
  68. }
  69.  
  70. /**
  71.  * Password input field
  72.  * @param string $sName field name
  73.  * @param string $sValue initial password value
  74.  * @param array $aAttribs (since 1.5.1) extra attributes
  75.  * @return string html formated password field
  76.  */
  77. function addPwField($sName, $sValue = null, $aAttribs=array()) {
  78.     $aAttribs['name']  = $sName;
  79.     $aAttribs['value'] = (! is_null($sValue) ? $sValue : '');
  80.     // add default css
  81.     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmpwfield';
  82.     return addInputField('password',$aAttribs);
  83. }
  84.  
  85. /**
  86.  * Form checkbox
  87.  * @param string $sName field name
  88.  * @param boolean $bChecked controls if field is checked
  89.  * @param string $sValue 
  90.  * @param array $aAttribs (since 1.5.1) extra attributes
  91.  * @return string html formated checkbox field
  92.  */
  93. function addCheckBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
  94.     $aAttribs['name'] = $sName;
  95.     if ($bChecked) $aAttribs['checked'] = 'checked';
  96.     if (! is_null($sValue)) $aAttribs['value'] = $sValue;
  97.     // add default css
  98.     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox';
  99.     return addInputField('checkbox',$aAttribs);
  100. }
  101.  
  102. /**
  103.  * Form radio box
  104.  * @param string $sName field name
  105.  * @param boolean $bChecked controls if field is selected
  106.  * @param string $sValue 
  107.  * @param array $aAttribs (since 1.5.1) extra attributes.
  108.  * @return string html formated radio box
  109.  */
  110. function addRadioBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
  111.     $aAttribs['name'] = $sName;
  112.     if ($bChecked) $aAttribs['checked'] = 'checked';
  113.     if (! is_null($sValue)) $aAttribs['value'] = $sValue;
  114.     if (! isset($aAttribs['id'])) $aAttribs['id'] = $sName . $sValue;
  115.     // add default css
  116.     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox';
  117.     return addInputField('radio', $aAttribs);
  118. }
  119.  
  120. /**
  121.  * A hidden form field.
  122.  * @param string $sName field name
  123.  * @param string $sValue field value
  124.  * @param array $aAttribs (since 1.5.1) extra attributes
  125.  * @return html formated hidden form field
  126.  */
  127. function addHidden($sName, $sValue, $aAttribs=array()) {
  128.     $aAttribs['name'] = $sName;
  129.     $aAttribs['value'] = $sValue;
  130.     // add default css
  131.     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmhiddenfield';
  132.     return addInputField('hidden', $aAttribs);
  133. }
  134.  
  135. /**
  136.  * An input textbox.
  137.  * @param string $sName field name
  138.  * @param string $sValue initial field value
  139.  * @param integer $iSize field size (number of characters)
  140.  * @param integer $iMaxlength maximum number of characters the user may enter
  141.  * @param array $aAttribs (since 1.5.1) extra attributes - should be given
  142.  *                         in the form array('attribute_name' => 'attribute_value', ...)
  143.  * @return string html formated text input field
  144.  */
  145. function addInput($sName, $sValue = '', $iSize = 0, $iMaxlength = 0, $aAttribs=array()) {
  146.     $aAttribs['name'] = $sName;
  147.     $aAttribs['value'] = $sValue;
  148.     if ($iSize) $aAttribs['size'] = (int)$iSize;
  149.     if ($iMaxlength) $aAttribs['maxlength'] = (int)$iMaxlength;
  150.     // add default css
  151.     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield';
  152.     return addInputField('text', $aAttribs);
  153. }
  154.  
  155. /**
  156.  * Function to create a selectlist from an array.
  157.  * @param string $sName field name
  158.  * @param array $aValues field values array ( key => value )  ->     <option value="key">value</option>
  159.  * @param mixed $default the key that will be selected
  160.  * @param boolean $bUsekeys use the keys of the array as option value or not
  161.  * @param array $aAttribs (since 1.5.1) extra attributes
  162.  * @return string html formated selection box
  163.  * @todo add attributes argument for option tags and default css
  164.  */
  165. function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array()) {
  166.     // only one element
  167.     if(count($aValues) == 1) {
  168.         $k = key($aValues); $v = array_pop($aValues);
  169.         return addHidden($sName, ($bUsekeys ? $k:$v), $aAttribs).
  170.             htmlspecialchars($v) . "\n";
  171.     }
  172.  
  173.     if (isset($aAttribs['id'])) {
  174.         $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
  175.         $label_close = '</label>';
  176.     } else {
  177.         $label_open = '';
  178.         $label_close = '';
  179.     }
  180.  
  181.     // create attribute string for select tag
  182.     $sAttribs = '';
  183.     foreach ($aAttribs as $key => $value) {
  184.         $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
  185.     }
  186.  
  187.     $ret = '<select name="'.htmlspecialchars($sName) . '"' . $sAttribs . ">\n";
  188.     foreach ($aValues as $k => $v) {
  189.         if(!$bUsekeys) $k = $v;
  190.         $ret .= '<option value="' .
  191.             htmlspecialchars( $k ) . '"' .
  192.             (($default == $k) ? ' selected="selected"' : '') .
  193.             '>' . $label_open . htmlspecialchars($v) . $label_close  ."</option>\n";
  194.     }
  195.     $ret .= "</select>\n";
  196.  
  197.     return $ret;
  198. }
  199.  
  200. /**
  201.  * Form submission button
  202.  * Note the switched value/name parameters!
  203.  * @param string $sValue button name
  204.  * @param string $sName submitted key name
  205.  * @param array $aAttribs (since 1.5.1) extra attributes
  206.  * @return string html formated submit input field
  207.  */
  208. function addSubmit($sValue, $sName = null, $aAttribs=array()) {
  209.     $aAttribs['value'] = $sValue;
  210.     if (! is_null($sName)) $aAttribs['name'] = $sName;
  211.     // add default css
  212.     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
  213.     return addInputField('submit', $aAttribs);
  214. }
  215. /**
  216.  * Form reset button
  217.  * @param string $sValue button name
  218.  * @param array $aAttribs (since 1.5.1) extra attributes
  219.  * @return string html formated reset input field
  220.  */
  221. function addReset($sValue, $aAttribs=array()) {
  222.     $aAttribs['value'] = $sValue;
  223.     // add default css
  224.     if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield';
  225.     return addInputField('reset', $aAttribs);
  226. }
  227.  
  228. /**
  229.  * Textarea form element.
  230.  * @param string $sName field name
  231.  * @param string $sText initial field value
  232.  * @param integer $iCols field width (number of chars)
  233.  * @param integer $iRows field height (number of character rows)
  234.  * @param array $aAttribs (since 1.5.1) extra attributes. function accepts string argument
  235.  *  for backward compatibility.
  236.  * @return string html formated text area field
  237.  */
  238. function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) {
  239.     $label_open = '';
  240.     $label_close = '';
  241.     if (is_array($aAttribs)) {
  242.         // maybe id can default to name?
  243.         if (isset($aAttribs['id'])) {
  244.             $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
  245.             $label_close = '</label>';
  246.         }
  247.         // add default css
  248.         if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea';
  249.         // create attribute string (do we have to sanitize keys?)
  250.         $sAttribs = '';
  251.         foreach ($aAttribs as $key => $value) {
  252.             $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
  253.         }
  254.     } elseif (is_string($aAttribs)) {
  255.         // backward compatibility mode. deprecated.
  256.         $sAttribs = ' ' . $aAttribs;
  257.     } else {
  258.         $sAttribs = '';
  259.     }
  260.     return '<textarea name="'.htmlspecialchars($sName).'" '.
  261.         'rows="'.(int)$iRows .'" cols="'.(int)$iCols.'"'.
  262.         $sAttribs . '>'. $label_open . htmlspecialchars($sText) . $label_close ."</textarea>\n";
  263. }
  264.  
  265. /**
  266.  * Make a <form> start-tag.
  267.  * @param string $sAction form handler URL
  268.  * @param string $sMethod http method used to submit form data. 'get' or 'post'
  269.  * @param string $sName form name used for identification (used for backward
  270.  *   compatibility). Use of id is recommended.
  271.  * @param string $sEnctype content type that is used to submit data. html 4.01
  272.  *   defaults to 'application/x-www-form-urlencoded'. Form with file field needs
  273.  *   'multipart/form-data' encoding type.
  274.  * @param string $sCharset charset that is used for submitted data
  275.  * @param array $aAttribs (since 1.5.1) extra attributes
  276.  * @return string html formated form start string
  277.  */
  278. function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) {
  279.     // id tags
  280.     if (! isset($aAttribs['id']) && ! empty($sName))
  281.         $aAttribs['id'] = $sName;
  282.  
  283.     if($sName) {
  284.         $sName = ' name="'.$sName.'"';
  285.     }
  286.     if($sEnctype) {
  287.         $sEnctype = ' enctype="'.$sEnctype.'"';
  288.     }
  289.     if($sCharset) {
  290.         $sCharset = ' accept-charset="'.htmlspecialchars($sCharset).'"';
  291.     }
  292.  
  293.     // create attribute string (do we have to sanitize keys?)
  294.     $sAttribs = '';
  295.     foreach ($aAttribs as $key => $value) {
  296.         $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
  297.     }
  298.  
  299.     return '<form action="'. $sAction .'" method="'. $sMethod .'"'.
  300.         $sEnctype . $sName . $sCharset . $sAttribs . ">\n";
  301. }

Documentation generated on Sat, 07 Oct 2006 16:11:06 +0300 by phpDocumentor 1.3.0RC6