[prev in list] [next in list] [prev in thread] [next in thread]
List: squirrelmail-cvs
Subject: [SM-CVS] CVS: squirrelmail/functions forms.php,1.16,1.17
From: Tomas Kuliavas <tokul () users ! sourceforge ! net>
Date: 2005-05-29 8:31:00
Message-ID: E1DcJCG-00051O-2d () sc8-pr-cvs1 ! sourceforge ! net
[Download RAW message or body]
Update of /cvsroot/squirrelmail/squirrelmail/functions
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18673
Modified Files:
forms.php
Log Message:
documenting form functions.
adding id tag support to every function instead of using it only in main function.
Index: forms.php
===================================================================
RCS file: /cvsroot/squirrelmail/squirrelmail/functions/forms.php,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -w -r1.16 -r1.17
--- forms.php 23 Apr 2005 12:07:34 -0000 1.16
+++ forms.php 29 May 2005 08:30:57 -0000 1.17
@@ -1,21 +1,42 @@
<?php
/**
- * forms.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 htmlentitied.
+ * All name, value attributes 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.
+ *
+ * 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.
+ *
+ * @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
* @version $Id$
* @package squirrelmail
* @subpackage forms
+ * @since 1.4.3 and 1.5.1
*/
/**
* 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
+ * 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
+ * @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.'"'.
@@ -28,39 +49,67 @@
/**
* 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
+ * @return string html formated password field
*/
-function addPwField($name , $value = null) {
- return addInputField('password', $name , $value);
+function addPwField($name , $value = null, $id = null) {
+ return addInputField('password', $name , $value, '', $id);
}
-
/**
* 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
+ * @return string html formated checkbox field
*/
-function addCheckBox($name, $checked = false, $value = null, $xtra = '') {
+function addCheckBox($name, $checked = false, $value = null, $xtra = '', $id = null) {
return addInputField('checkbox', $name, $value,
- ($checked ? ' checked="checked"' : '') . ' ' . $xtra);
+ ($checked ? ' checked="checked"' : '') . ' ' . $xtra, $id);
}
/**
* Form radio box
- */
-function addRadioBox($name, $checked = false, $value = null) {
+ * @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
+ * @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"' : ''), $name . $value);
+ ($checked ? ' checked="checked"' : ''), $id);
}
/**
* 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
+ * @return html formated hidden form field
*/
-function addHidden($name, $value) {
- return addInputField('hidden', $name, $value);
+function addHidden($name, $value, $id = null) {
+ return addInputField('hidden', $name, $value, '', $id);
}
/**
* 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
+ * @return string html formated text input field
*/
-function addInput($name, $value = '', $size = 0, $maxlength = 0) {
+function addInput($name, $value = '', $size = 0, $maxlength = 0, $id = null) {
$attr = '';
if ($size) {
@@ -70,34 +119,43 @@
$attr.= ' maxlength="'.(int)$maxlength .'"';
}
- return addInputField('text', $name, $value, $attr);
+ return addInputField('text', $name, $value, $attr, $id);
}
-
/**
* Function to create a selectlist from an array.
- * Usage:
- * name: html name attribute
- * values: array ( key => value ) -> <option value="key">value</option>
- * default: the key that will be selected
- * usekeys: use the keys of the array as option value or not
+ * @param string $name field name
+ * @param array $values 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
+ * @return string html formated selection box
*/
-function addSelect($name, $values, $default = null, $usekeys = false)
-{
+function addSelect($name, $values, $default = null, $usekeys = false, $id = null) {
// only one element
if(count($values) == 1) {
$k = key($values); $v = array_pop($values);
- return addHidden($name, ($usekeys ? $k:$v)).
+ return addHidden($name, ($usekeys ? $k:$v), $id).
htmlspecialchars($v) . "\n";
}
- $ret = '<select name="'.htmlspecialchars($name) . "\">\n";
+ if (! is_null($id)) {
+ $id = ' id="'.htmlspecialchars($id).'"';
+ $label_open = '<label for="'.htmlspecialchars($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;
$ret .= '<option value="' .
htmlspecialchars( $k ) . '"' .
(($default == $k) ? ' selected="selected"' : '') .
- '>' . htmlspecialchars($v) ."</option>\n";
+ '>' . $label_open . htmlspecialchars($v) . $label_close ."</option>\n";
}
$ret .= "</select>\n";
@@ -107,31 +165,62 @@
/**
* 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
+ * @return string html formated submit input field
+ */
+function addSubmit($value, $name = null, $id = null) {
+ return addInputField('submit', $name, $value, '', $id);
+}
+/**
+ * Form reset button
+ * @param string $value button name
+ * @param string $id (since 1.5.1) assigns unique identifier to an element
+ * @return string html formated reset input field
*/
-function addSubmit($value, $name = null) {
- return addInputField('submit', $name, $value);
-}
-/**
- * Form reset button, $value = caption
- */
-function addReset($value) {
- return addInputField('reset', null, $value);
+function addReset($value, $id = null) {
+ return addInputField('reset', null, $value, '', $id);
}
/**
* Textarea form element.
- */
-function addTextArea($name, $text = '', $cols = 40, $rows = 10, $attr = '') {
+ * @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
+ * @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>';
+ } else {
+ $label_open = '';
+ $label_close = '';
+ }
return '<textarea name="'.htmlspecialchars($name).'" '.
'rows="'.(int)$rows .'" cols="'.(int)$cols.'" '.
- $attr . '>'.htmlspecialchars($text) ."</textarea>\n";
+ $attr . $id . '>'. $label_open . htmlspecialchars($text) . $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
+ * compatibility). Use of id is recommended.
+ * @param string $enctype 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
+ * @return string html formated form start string
*/
-function addForm($action, $method = 'post', $name = '', $enctype = '', $charset = '')
-{
+function addForm($action, $method = 'post', $name = '', $enctype = '', $charset = '', $id = '') {
if($name) {
$name = ' name="'.$name.'"';
}
@@ -141,9 +230,12 @@
if($charset) {
$charset = ' accept-charset="'.htmlspecialchars($charset).'"';
}
+ if (!empty($id)) {
+ $id = ' id="'.htmlspecialchars($id).'"';
+ }
return '<form action="'. $action .'" method="'. $method .'"'.
- $enctype . $name . $charset . ">\n";
+ $enctype . $name . $charset . $id . ">\n";
}
?>
\ No newline at end of file
-------------------------------------------------------
This SF.Net email is sponsored by Yahoo.
Introducing Yahoo! Search Developer Network - Create apps using Yahoo!
Search APIs Find out how you can build Yahoo! directly into your own
Applications - visit http://developer.yahoo.net/?fr=offad-ysdn-ostg-q22005
--
squirrelmail-cvs mailing list
List Address: squirrelmail-cvs@lists.sourceforge.net
List Info: https://lists.sourceforge.net/lists/listinfo/squirrelmail-cvs
http://squirrelmail.org/cvs
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic