<?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().
+ * Functions to build forms in a safe and consistent manner.
+ * All attribute values are sanitized with sm_encode_html_special_chars().
+//FIXME: I think the Template class might be better place to sanitize inside assign() method
*
* 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.
*
- * 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.
+ *
+ * * 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 2004-2020 The SquirrelMail Project Team
+ * @license http://opensource.org/licenses/gpl-license.php GNU Public License
* @version $Id$
* @package squirrelmail
* @subpackage forms
/**
* 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'])) {
+ /**
+ * if 'id' is not set, set it to 'name' and replace brackets
+ * with underscores. 'name' might contain field name with squire
+ * brackets (array). Brackets are not allowed in id (validator.w3.org
+ * fails to validate document). According to html 4.01 manual cdata
+ * type description, 'name' attribute uses same type, but validator.w3.org
+ * does not barf on brackets in 'name' attributes.
+ */
+ $aAttribs['id'] = strtr($aAttribs['name'],'[]','__');
+ }
+
+ global $oTemplate;
+
+ $oTemplate->assign('type', $sType);
+//FIXME: all the values in the $aAttribs list used to go thru sm_encode_html_special_chars()... I would propose that most everything that is assigned to the template should go thru that *in the template class* on its way between here and the actual template file. Otherwise we have to do something like: foreach ($aAttribs as $key => $value) $aAttribs[$key] = sm_encode_html_special_chars($value);
+ $oTemplate->assign('aAttribs', $aAttribs);
+
+ return $oTemplate->fetch('input.tpl');
+
}
/**
* 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
+ * @param string $sName field name
+ * @param string $sValue initial password 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 password field
*/
-function addPwField($name , $value = null, $id = null) {
- return addInputField('password', $name , $value, '', $id);
+function addPwField($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'] = '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 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 string $sName Field name
+ * @param array $aValues Field values array(key => value) results in:
+ * <option value="key">value</option>,
+ * although if $bUsekeys is FALSE, then it changes to:
+ * <option value="value">value</option>
+ * @param mixed $default The key(s) that will be selected (it is OK to pass
+ * in an array here in the case of multiple select lists)
+ * @param boolean $bUsekeys Use the keys of the array as option value or not
+ * @param array $aAttribs (since 1.5.1) Extra attributes
+ * @param boolean $bMultiple When TRUE, a multiple select list will be shown
+ * (OPTIONAL; default is FALSE (single select list))
+ * @param int $iSize Desired height of multiple select boxes
+ * (OPTIONAL; default is SMOPT_SIZE_NORMAL)
+ * (only applicable when $bMultiple is TRUE)
+ *
* @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(), $bMultiple = FALSE, $iSize = SMOPT_SIZE_NORMAL) {
// only one element
- if(count($values) == 1) {
- $k = key($values); $v = array_pop($values);
- return addHidden($name, ($usekeys ? $k:$v), $id).
- htmlspecialchars($v) . "\n";
+ if (!$bMultiple && count($aValues) == 1) {
+ $k = key($aValues); $v = array_pop($aValues);
+ return addHidden($sName, ($bUsekeys ? $k : $v), $aAttribs)
+ . sm_encode_html_special_chars($v);
}
- if (! is_null($id)) {
- $id = ' id="'.htmlspecialchars($id).'"';
- $label_open = '<label for="'.htmlspecialchars($id).'">';
- $label_close = '</label>';
- } else {
- $id = '';
- $label_open = '';
- $label_close = '';
- }
+ if (! isset($aAttribs['id'])) $aAttribs['id'] = $sName;
+
+ // make sure $default is an array, since multiple select lists
+ // need the chance to have more than one default...
+ //
+ if (!is_array($default))
+ $default = array($default);
- $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"' : '') .
- '>' . $label_open . htmlspecialchars($v) . $label_close ."</option>\n";
- }
- $ret .= "</select>\n";
- return $ret;
+ global $oTemplate;
+
+//FIXME: all the values in the $aAttribs list and $sName and both the keys and values in $aValues used to go thru sm_encode_html_special_chars()... I would propose that most everything that is assigned to the template should go thru that *in the template class* on its way between here and the actual template file. Otherwise we have to do something like: foreach ($aAttribs as $key => $value) $aAttribs[$key] = sm_encode_html_special_chars($value); $sName = sm_encode_html_special_chars($sName); $aNewValues = array(); foreach ($aValues as $key => $value) $aNewValues[sm_encode_html_special_chars($key)] = sm_encode_html_special_chars($value); $aValues = $aNewValues; And probably this too because it has to be matched to a value that has already been sanitized: $default = sm_encode_html_special_chars($default); (oops, watch out for when $default is an array! (multiple select lists))
+ $oTemplate->assign('aAttribs', $aAttribs);
+ $oTemplate->assign('aValues', $aValues);
+ $oTemplate->assign('bUsekeys', $bUsekeys);
+ $oTemplate->assign('default', $default);
+ $oTemplate->assign('name', $sName);
+ $oTemplate->assign('multiple', $bMultiple);
+ $oTemplate->assign('size', $iSize);
+
+ return $oTemplate->fetch('select.tpl');
+}
+
+/**
+ * Normal button
+ *
+ * Note the switched value/name parameters!
+ * Note also that regular buttons are not very useful unless
+ * used with onclick handlers, thus are only really appropriate
+ * if you use them after having checked if JavaScript is turned
+ * on by doing this: if (checkForJavascript()) ...
+ *
+ * @param string $sValue button name
+ * @param string $sName key name
+ * @param array $aAttribs extra attributes
+ *
+ * @return string html formated submit input field
+ *
+ * @since 1.5.2
+ */
+function addButton($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('button', $aAttribs);
}
/**
* 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 (OPTIONAL; default empty)
+ * @param integer $iCols field width (number of chars) (OPTIONAL; default 40)
+ * @param integer $iRows field height (number of character rows) (OPTIONAL; default 10)
+ * @param array $aAttribs (since 1.5.1) extra attributes (OPTIONAL; default empty)
+ *
* @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 = '';
+function addTextArea($sName, $sText = '', $iCols = 40, $iRows = 10, $aAttribs = array()) {
+
+ // no longer accept string arguments for attribs; print
+ // backtrace to help people fix their code
+ //FIXME: throw error instead?
+ if (!is_array($aAttribs)) {
+ echo '$aAttribs argument to addTextArea() must be an array<br /><pre>';
+ debug_print_backtrace();
+ echo '</pre><br />';
+ exit;
}
- return '<textarea name="'.htmlspecialchars($name).'" '.
- 'rows="'.(int)$rows .'" cols="'.(int)$cols.'" '.
- $attr . $id . '>'. $label_open . htmlspecialchars($text) . $label_close ."</textarea>\n";
+
+ // add default css
+ else if (!isset($aAttribs['class'])) $aAttribs['class'] = 'sqmtextarea';
+
+ if ( empty( $aAttribs['id'] ) ) {
+ $aAttribs['id'] = strtr($sName,'[]','__');
+ }
+
+ global $oTemplate;
+
+//FIXME: all the values in the $aAttribs list as well as $sName and $sText used to go thru sm_encode_html_special_chars()... I would propose that most everything that is assigned to the template should go thru that *in the template class* on its way between here and the actual template file. Otherwise we have to do something like: foreach ($aAttribs as $key => $value) $aAttribs[$key] = sm_encode_html_special_chars($value); $sName = sm_encode_html_special_chars($sName); $sText = sm_encode_html_special_chars($sText);
+ $oTemplate->assign('aAttribs', $aAttribs);
+ $oTemplate->assign('name', $sName);
+ $oTemplate->assign('text', $sText);
+ $oTemplate->assign('cols', (int)$iCols);
+ $oTemplate->assign('rows', (int)$iRows);
+
+ return $oTemplate->fetch('textarea.tpl');
}
/**
* 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
+ *
+ * @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 instead.
+ * @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 $sCharset charset that is used for submitted data
+ * @param array $aAttribs (since 1.5.1) extra attributes
+ * @param boolean $bAddToken (since 1.5.2) When given as a string or as boolean TRUE,
+ * a hidden input is also added to the form containing a
+ * security token. When given as TRUE, the input name is
+ * "smtoken"; otherwise the name is the string that is
+ * given for this parameter. When FALSE, no hidden token
+ * input field is added. (OPTIONAL; default not used)
+ *
* @return string html formated form start string
+ *
*/
-function addForm($action, $method = 'post', $name = '', $enctype = '', $charset = '', $id = '') {
- if($name) {
- $name = ' name="'.$name.'"';
- }
- if($enctype) {
- $enctype = ' enctype="'.$enctype.'"';
- }
- if($charset) {
- $charset = ' accept-charset="'.htmlspecialchars($charset).'"';
- }
- if (!empty($id)) {
- $id = ' id="'.htmlspecialchars($id).'"';
+function addForm($sAction, $sMethod = 'post', $sName = '', $sEnctype = '', $sCharset = '', $aAttribs = array(), $bAddToken = FALSE) {
+
+ global $oTemplate;
+
+//FIXME: all the values in the $aAttribs list as well as $charset used to go thru sm_encode_html_special_chars()... I would propose that most everything that is assigned to the template should go thru that *in the template class* on its way between here and the actual template file. Otherwise we have to do something like: foreach ($aAttribs as $key => $value) $aAttribs[$key] = sm_encode_html_special_chars($value); $sCharset = sm_encode_html_special_chars($sCharset);
+ $oTemplate->assign('aAttribs', $aAttribs);
+ $oTemplate->assign('name', $sName);
+ $oTemplate->assign('method', $sMethod);
+ $oTemplate->assign('action', $sAction);
+ $oTemplate->assign('enctype', $sEnctype);
+ $oTemplate->assign('charset', $sCharset);
+
+ $sForm = $oTemplate->fetch('form.tpl');
+
+ if ($bAddToken) {
+ $sForm .= addHidden((is_string($bAddToken) ? $bAddToken : 'smtoken'),
+ sm_generate_security_token());
}
- return '<form action="'. $action .'" method="'. $method .'"'.
- $enctype . $name . $charset . $id . ">\n";
+ return $sForm;
+}
+
+/**
+ * Creates unique widget names
+ *
+ * Names are formatted as such: "send1", "send2", "send3", etc.,
+ * where "send" in this example is what was given for $base_name
+ *
+ * @param string $base_name The name upon which to base the
+ * returned widget name.
+ * @param boolean $return_count When TRUE, this function will
+ * return the last number used to
+ * create a widget name for $base_name
+ * (OPTIONAL; default = FALSE).
+ *
+ * @return mixed When $return_output is FALSE, a string containing
+ * the unique widget name; otherwise an integer with
+ * the last number used to create the last widget
+ * name for the given $base_name (where 0 (zero) means
+ * that no such widgets have been created yet).
+ *
+ * @since 1.5.2
+ *
+ */
+function unique_widget_name($base_name, $return_count=FALSE)
+{
+ static $counts = array();
+
+ if (!isset($counts[$base_name]))
+ $counts[$base_name] = 0;
+
+ if ($return_count)
+ return $counts[$base_name];
+
+ ++$counts[$base_name];
+ return $base_name . $counts[$base_name];
}
-?>
\ No newline at end of file
projects / squirrelmail.git / blobdiff