X-Git-Url: https://vcs.fsf.org/?p=squirrelmail.git;a=blobdiff_plain;f=functions%2Fforms.php;h=feefdadbd9c1ba43dafea036fbbc8cf0d1060136;hp=5f515d2bab8ca7673ab4301fe2cf6d55ebdcba7f;hb=4b4abf93a9624311afef0c385023724ee46a2b60;hpb=ed6d3334c44c7032904a527b8a69364463ce5c67

diff --git a/functions/forms.php b/functions/forms.php
index 5f515d2b..feefdadb 100644
--- a/functions/forms.php
+++ b/functions/forms.php
@@ -1,24 +1,31 @@
 <?php
+
 /**
  * forms.php - html form functions
  *
- * Copyright (c) 2004-2005 The SquirrelMail Project Team
- * Licensed under the GNU GPL. For full terms see the file COPYING.
- *
  * Functions to build HTML forms in a safe and consistent manner.
- * All name, value attributes are sanitized with htmlspecialchars().
+ * All attribute values are sanitized with htmlspecialchars().
  *
  * Currently functions don't provide simple wrappers for file and 
  * image input fields, support only submit and reset buttons and use 
- * input fields for buttons.
+ * html input tags for buttons.
+ *
+ * Since 1.5.1:
+ *
+ *  * all form functions should support id tags. Original 
+ *  idea by dugan <at> passwall.com. Tags can be used for Section 508 
+ *  or WAI compliance.
+ *
+ *  * input tag functions accept extra html attributes that can be submitted 
+ *  in $aAttribs array.
  *
- * Since 1.5.1 all form functions should support id tags. Original 
- * idea by dugan <at> passwall.com. Tags can be used for Section 508 
- * or WAI compliance.
+ *  * default css class attributes are added.
  *
  * @link http://www.section508.gov/ Section 508
  * @link http://www.w3.org/WAI/ Web Accessibility Initiative (WAI)
  * @link http://www.w3.org/TR/html4/ W3.org HTML 4.01 form specs
+ * @copyright &copy; 2004-2005 The SquirrelMail Project Team
+ * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  * @version $Id$
  * @package squirrelmail
  * @subpackage forms
@@ -28,130 +35,150 @@
 /**
  * Helper function to create form fields, not to be called directly,
  * only by other functions below.
- * @param string $type type of input field. Possible values (html 4.01 
+ * 
+ * Function used different syntax before 1.5.1
+ * @param string $sType type of input field. Possible values (html 4.01 
  *  specs.): text, password, checkbox, radio, submit, reset, file, 
  *  hidden, image, button.
- * @param string $name form field name
- * @param string $value initial field value
- * @param string $attributes extra attributes
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param array $aAttribs (since 1.5.1) extra attributes. Array key is 
+ *  attribute name, array value is attribute value. Array keys must use  
+ *  lowercase.
  * @return string html formated input field
  * @deprecated use other functions that provide simple wrappers to this function
  */
-function addInputField($type, $name = null, $value = null, $attributes = '', $id = null) {
-    return '<input type="'.$type.'"'.
-        ($name  !== null ? ' name="'.htmlspecialchars($name).'"'   : '').
-        ($id  !== null ? ' id="'.htmlspecialchars($id).'"'
-            : ($name  !== null ? ' id="'.htmlspecialchars($name).'"'   : '')).
-        ($value !== null ? ' value="'.htmlspecialchars($value).'"' : '').
-        $attributes . " />\n";
+function addInputField($sType, $aAttribs=array()) {
+    $sAttribs = '';
+    // define unique identifier
+    if (! isset($aAttribs['id']) && isset($aAttribs['name']) && ! is_null($aAttribs['name'])) {
+        $aAttribs['id'] = $aAttribs['name'];
+    }
+    // create attribute string (do we have to sanitize keys?)
+    foreach ($aAttribs as $key => $value) {
+        $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
+    }
+    return '<input type="'.$sType.'"'.$sAttribs." />\n";
 }
 
 /**
  * Password input field
- * @param string $name field name
- * @param string $value initial password value
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param string $sName field name
+ * @param string $sValue initial password value
+ * @param array $aAttribs (since 1.5.1) extra attributes
  * @return string html formated password field
  */
-function addPwField($name , $value = null, $id = null) {
-    return addInputField('password', $name , $value, '', $id);
+function addPwField($sName, $sValue = null, $aAttribs=array()) {
+    $aAttribs['name']  = $sName;
+    $aAttribs['value'] = (! is_null($sValue) ? $sValue : '');
+    // add default css
+    if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmpwfield';
+    return addInputField('password',$aAttribs);
 }
 
 /**
  * Form checkbox
- * @param string $name field name
- * @param boolean $checked controls if field is checked
- * @param string $value
- * @param string $xtra (since 1.5.1) extra field attributes
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param string $sName field name
+ * @param boolean $bChecked controls if field is checked
+ * @param string $sValue
+ * @param array $aAttribs (since 1.5.1) extra attributes
  * @return string html formated checkbox field
  */
-function addCheckBox($name, $checked = false, $value = null, $xtra = '', $id = null) {
-    return addInputField('checkbox', $name, $value,
-        ($checked ? ' checked="checked"' : '') . ' ' . $xtra, $id);
+function addCheckBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
+    $aAttribs['name'] = $sName;
+    if ($bChecked) $aAttribs['checked'] = 'checked';
+    if (! is_null($sValue)) $aAttribs['value'] = $sValue;
+    // add default css
+    if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmcheckbox';
+    return addInputField('checkbox',$aAttribs);
 }
 
 /**
  * Form radio box
- * @param string $name field name
- * @param boolean $checked controls if field is selected
- * @param string $value
- * @param string $id (since 1.5.1) assigns unique identifier to an element. 
- *  Defaults to combined $name and $value string
+ * @param string $sName field name
+ * @param boolean $bChecked controls if field is selected
+ * @param string $sValue
+ * @param array $aAttribs (since 1.5.1) extra attributes.
  * @return string html formated radio box
  */
-function addRadioBox($name, $checked = false, $value = null, $id = '') {
-    if (empty($id)) {
-        $id = $name . $value;
-    }
-    return addInputField('radio', $name, $value,
-        ($checked ? ' checked="checked"' : ''), $id);
+function addRadioBox($sName, $bChecked = false, $sValue = null, $aAttribs=array()) {
+    $aAttribs['name'] = $sName;
+    if ($bChecked) $aAttribs['checked'] = 'checked';
+    if (! is_null($sValue)) $aAttribs['value'] = $sValue;
+    if (! isset($aAttribs['id'])) $aAttribs['id'] = $sName . $sValue;
+    // add default css
+    if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmradiobox';
+    return addInputField('radio', $aAttribs);
 }
 
 /**
  * A hidden form field.
- * @param string $name field name
- * @param string $value field value
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param string $sName field name
+ * @param string $sValue field value
+ * @param array $aAttribs (since 1.5.1) extra attributes
  * @return html formated hidden form field
  */
-function addHidden($name, $value, $id = null) {
-    return addInputField('hidden', $name, $value, '', $id);
+function addHidden($sName, $sValue, $aAttribs=array()) {
+    $aAttribs['name'] = $sName;
+    $aAttribs['value'] = $sValue;
+    // add default css
+    if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmhiddenfield';
+    return addInputField('hidden', $aAttribs);
 }
 
 /**
  * An input textbox.
- * @param string $name field name
- * @param string $value initial field value
- * @param integer $size field size (number of characters)
- * @param integer $maxlength maximum number of characters the user may enter
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param string $sName field name
+ * @param string $sValue initial field value
+ * @param integer $iSize field size (number of characters)
+ * @param integer $iMaxlength maximum number of characters the user may enter
+ * @param array $aAttribs (since 1.5.1) extra attributes - should be given
+ *                        in the form array('attribute_name' => 'attribute_value', ...)
  * @return string html formated text input field
  */
-function addInput($name, $value = '', $size = 0, $maxlength = 0, $id = null) {
-
-    $attr = '';
-    if ($size) {
-        $attr.= ' size="'.(int)$size.'"';
-    }
-    if ($maxlength) {
-        $attr.= ' maxlength="'.(int)$maxlength .'"';
-    }
-
-    return addInputField('text', $name, $value, $attr, $id);
+function addInput($sName, $sValue = '', $iSize = 0, $iMaxlength = 0, $aAttribs=array()) {
+    $aAttribs['name'] = $sName;
+    $aAttribs['value'] = $sValue;
+    if ($iSize) $aAttribs['size'] = (int)$iSize;
+    if ($iMaxlength) $aAttribs['maxlength'] = (int)$iMaxlength;
+    // add default css
+    if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextfield';
+    return addInputField('text', $aAttribs);
 }
 
 /**
  * Function to create a selectlist from an array.
- * @param string $name field name
- * @param array $values field values array ( key => value )  ->     <option value="key">value</option>
+ * @param string $sName field name
+ * @param array $aValues field values array ( key => value )  ->     <option value="key">value</option>
  * @param mixed $default the key that will be selected
- * @param boolean $usekeys use the keys of the array as option value or not
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param boolean $bUsekeys use the keys of the array as option value or not
+ * @param array $aAttribs (since 1.5.1) extra attributes
  * @return string html formated selection box
+ * @todo add attributes argument for option tags and default css
  */
-function addSelect($name, $values, $default = null, $usekeys = false, $id = null) {
+function addSelect($sName, $aValues, $default = null, $bUsekeys = false, $aAttribs = array()) {
     // only one element
-    if(count($values) == 1) {
-        $k = key($values); $v = array_pop($values);
-        return addHidden($name, ($usekeys ? $k:$v), $id).
+    if(count($aValues) == 1) {
+        $k = key($aValues); $v = array_pop($aValues);
+        return addHidden($sName, ($bUsekeys ? $k:$v), $aAttribs).
             htmlspecialchars($v) . "\n";
     }
 
-    if (! is_null($id)) {
-        $id = ' id="'.htmlspecialchars($id).'"';
-        $label_open = '<label for="'.htmlspecialchars($id).'">';
+    if (isset($aAttribs['id'])) {
+        $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
         $label_close = '</label>';
     } else {
-        $id = '';
         $label_open = '';
         $label_close = '';
     }
 
-    $ret = '<select name="'.htmlspecialchars($name) . '"' . $id . ">\n";
-    foreach ($values as $k => $v) {
-        if(!$usekeys) $k = $v;
+    // create attribute string for select tag
+    $sAttribs = '';
+    foreach ($aAttribs as $key => $value) {
+        $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
+    }
+
+    $ret = '<select name="'.htmlspecialchars($sName) . '"' . $sAttribs . ">\n";
+    foreach ($aValues as $k => $v) {
+        if(!$bUsekeys) $k = $v;
         $ret .= '<option value="' .
             htmlspecialchars( $k ) . '"' .
             (($default == $k) ? ' selected="selected"' : '') .
@@ -165,77 +192,104 @@ function addSelect($name, $values, $default = null, $usekeys = false, $id = null
 /**
  * Form submission button
  * Note the switched value/name parameters!
- * @param string $value button name
- * @param string $name submitted key name
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param string $sValue button name
+ * @param string $sName submitted key name
+ * @param array $aAttribs (since 1.5.1) extra attributes
  * @return string html formated submit input field
  */
-function addSubmit($value, $name = null, $id = null) {
-    return addInputField('submit', $name, $value, '', $id);
+function addSubmit($sValue, $sName = null, $aAttribs=array()) {
+    $aAttribs['value'] = $sValue;
+    if (! is_null($sName)) $aAttribs['name'] = $sName;
+    // add default css
+    if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmsubmitfield';
+    return addInputField('submit', $aAttribs);
 }
 /**
  * Form reset button
- * @param string $value button name
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param string $sValue button name
+ * @param array $aAttribs (since 1.5.1) extra attributes
  * @return string html formated reset input field
  */
-function addReset($value, $id = null) {
-    return addInputField('reset', null, $value, '', $id);
+function addReset($sValue, $aAttribs=array()) {
+    $aAttribs['value'] = $sValue;
+    // add default css
+    if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmresetfield';
+    return addInputField('reset', $aAttribs);
 }
 
 /**
  * Textarea form element.
- * @param string $name field name
- * @param string $text initial field value
- * @param integer $cols field width (number of chars)
- * @param integer $rows field height (number of character rows)
- * @param string $attr extra attributes
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param string $sName field name
+ * @param string $sText initial field value
+ * @param integer $iCols field width (number of chars)
+ * @param integer $iRows field height (number of character rows)
+ * @param array $aAttribs (since 1.5.1) extra attributes. function accepts string argument 
+ * for backward compatibility.
  * @return string html formated text area field
  */
-function addTextArea($name, $text = '', $cols = 40, $rows = 10, $attr = '', $id = '') {
-    if (!empty($id)) {
-        $id = ' id="'. htmlspecialchars($id) . '"';
-        $label_open = '<label for="'.htmlspecialchars($id).'">';
-        $label_close = '</label>';
+function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) {
+    $label_open = '';
+    $label_close = '';
+    if (is_array($aAttribs)) {
+        // maybe id can default to name?
+        if (isset($aAttribs['id'])) {
+            $label_open = '<label for="'.htmlspecialchars($aAttribs['id']).'">';
+            $label_close = '</label>';
+        }
+        // add default css
+        if (! isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea';
+        // create attribute string (do we have to sanitize keys?)
+        $sAttribs = '';
+        foreach ($aAttribs as $key => $value) {
+            $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
+        }
+    } elseif (is_string($aAttribs)) {
+        // backward compatibility mode. deprecated.
+        $sAttribs = ' ' . $aAttribs;
     } else {
-        $label_open = '';
-        $label_close = '';
+        $sAttribs = '';
     }
-    return '<textarea name="'.htmlspecialchars($name).'" '.
-        'rows="'.(int)$rows .'" cols="'.(int)$cols.'" '.
-        $attr . $id . '>'. $label_open . htmlspecialchars($text) . $label_close ."</textarea>\n";
+    return '<textarea name="'.htmlspecialchars($sName).'" '.
+        'rows="'.(int)$iRows .'" cols="'.(int)$iCols.'"'.
+        $sAttribs . '>'. $label_open . htmlspecialchars($sText) . $label_close ."</textarea>\n";
 }
 
 /**
  * Make a <form> start-tag.
- * @param string $action form handler URL
- * @param string $method http method used to submit form data. 'get' or 'post'
- * @param string $name form name used for identification (used for backward 
+ * @param string $sAction form handler URL
+ * @param string $sMethod http method used to submit form data. 'get' or 'post'
+ * @param string $sName form name used for identification (used for backward 
  *  compatibility). Use of id is recommended.
- * @param string $enctype content type that is used to submit data. html 4.01 
+ * @param string $sEnctype content type that is used to submit data. html 4.01 
  *  defaults to 'application/x-www-form-urlencoded'. Form with file field needs 
  *  'multipart/form-data' encoding type.
- * @param string $charset charset that is used for submitted data
- * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @param string $sCharset charset that is used for submitted data
+ * @param array $aAttribs (since 1.5.1) extra attributes
  * @return string html formated form start string
  */
-function addForm($action, $method = 'post', $name = '', $enctype = '', $charset = '', $id = '') {
-    if($name) {
-        $name = ' name="'.$name.'"';
+function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array()) {
+    // id tags
+    if (! isset($aAttribs['id']) && ! empty($sName))
+        $aAttribs['id'] = $sName;
+
+    if($sName) {
+        $sName = ' name="'.$sName.'"';
     }
-    if($enctype) {
-        $enctype = ' enctype="'.$enctype.'"';
+    if($sEnctype) {
+        $sEnctype = ' enctype="'.$sEnctype.'"';
     }
-    if($charset) {
-        $charset = ' accept-charset="'.htmlspecialchars($charset).'"';
+    if($sCharset) {
+        $sCharset = ' accept-charset="'.htmlspecialchars($sCharset).'"';
     }
-    if (!empty($id)) {
-        $id = ' id="'.htmlspecialchars($id).'"';
+
+    // create attribute string (do we have to sanitize keys?)
+    $sAttribs = '';
+    foreach ($aAttribs as $key => $value) {
+        $sAttribs.= ' ' . $key . (! is_null($value) ? '="'.htmlspecialchars($value).'"':'');
     }
 
-    return '<form action="'. $action .'" method="'. $method .'"'.
-        $enctype . $name . $charset . $id . ">\n";
+    return '<form action="'. $sAction .'" method="'. $sMethod .'"'.
+        $sEnctype . $sName . $sCharset . $sAttribs . ">\n";
 }
 
 ?>
\ No newline at end of file