/functions/forms.php

Description

forms.php - html form functions

Functions to build forms in a safe and consistent manner. All attribute values are sanitized with sm_encode_html_special_chars().

Currently functions don't provide simple wrappers for file and image input fields, support only submit and reset buttons and use 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.

* default css class attributes are added.

Functions
addButton (line 233)

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()) ...

  • return: html formated submit input field
  • since: 1.5.2
string addButton (string $sValue, [string $sName = null], [array $aAttribs = array()])
  • string $sValue: button name
  • string $sName: key name
  • array $aAttribs: extra attributes
addCheckBox (line 103)

Form checkbox

  • return: html formated checkbox field
string addCheckBox (string $sName, [boolean $bChecked = false], [string $sValue = null], [array $aAttribs = array()])
  • string $sName: field name
  • boolean $bChecked: controls if field is checked
  • string $sValue
  • array $aAttribs: (since 1.5.1) extra attributes
addForm (line 335)

Make a <form> start-tag.

  • return: html formated form start string
string addForm (string $sAction, [string $sMethod = 'post'], [string $sName = ''], [string $sEnctype = ''], [string $sCharset = ''], [array $aAttribs = array()], [boolean $bAddToken = FALSE])
  • string $sAction: form handler URL
  • string $sMethod: http method used to submit form data. 'get' or 'post'
  • string $sName: form name used for identification (used for backward compatibility). Use of id is recommended instead.
  • 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.
  • string $sCharset: charset that is used for submitted data
  • array $aAttribs: (since 1.5.1) extra attributes
  • 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)
addHidden (line 137)

A hidden form field.

  • return: formated hidden form field
html addHidden (string $sName, string $sValue, [array $aAttribs = array()])
  • string $sName: field name
  • string $sValue: field value
  • array $aAttribs: (since 1.5.1) extra attributes
addInput (line 155)

An input textbox.

  • return: html formated text input field
string addInput (string $sName, [string $sValue = ''], [integer $iSize = 0], [integer $iMaxlength = 0], [array $aAttribs = array()])
  • string $sName: field name
  • string $sValue: initial field value
  • integer $iSize: field size (number of characters)
  • integer $iMaxlength: maximum number of characters the user may enter
  • array $aAttribs: (since 1.5.1) extra attributes - should be given in the form array('attribute_name' => 'attribute_value', ...)
addInputField (line 50)

Helper function to create form fields, not to be called directly, only by other functions below.

Function used different syntax before 1.5.1

  • return: html formated input field
  • deprecated: use other functions that provide simple wrappers to this function
string addInputField (string $sType, [array $aAttribs = array()])
  • string $sType: type of input field. Possible values (html 4.01 specs.): text, password, checkbox, radio, submit, reset, file, hidden, image, button.
  • array $aAttribs: (since 1.5.1) extra attributes. Array key is attribute name, array value is attribute value. Array keys must use lowercase.
addPwField (line 85)

Password input field

  • return: html formated password field
string addPwField (string $sName, [string $sValue = ''], [integer $iSize = 0], [integer $iMaxlength = 0], [array $aAttribs = array()])
  • string $sName: field name
  • string $sValue: initial password value
  • integer $iSize: field size (number of characters)
  • integer $iMaxlength: maximum number of characters the user may enter
  • array $aAttribs: (since 1.5.1) extra attributes - should be given in the form array('attribute_name' => 'attribute_value', ...)
addRadioBox (line 120)

Form radio box

  • return: html formated radio box
string addRadioBox (string $sName, [boolean $bChecked = false], [string $sValue = null], [array $aAttribs = array()])
  • string $sName: field name
  • boolean $bChecked: controls if field is selected
  • string $sValue
  • array $aAttribs: (since 1.5.1) extra attributes.
addReset (line 263)

Form reset button

  • return: html formated reset input field
string addReset (string $sValue, [array $aAttribs = array()])
  • string $sValue: button name
  • array $aAttribs: (since 1.5.1) extra attributes
addSelect (line 185)

Function to create a selectlist from an array.

  • return: html formated selection box
  • todo: add attributes argument for option tags and default css
string addSelect (string $sName, array $aValues, [mixed $default = null], [boolean $bUsekeys = false], [array $aAttribs = array()], [boolean $bMultiple = FALSE], [int $iSize = SMOPT_SIZE_NORMAL])
  • string $sName: Field name
  • 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>
  • 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)
  • boolean $bUsekeys: Use the keys of the array as option value or not
  • array $aAttribs: (since 1.5.1) Extra attributes
  • boolean $bMultiple: When TRUE, a multiple select list will be shown (OPTIONAL; default is FALSE (single select list))
  • int $iSize: Desired height of multiple select boxes (OPTIONAL; default is SMOPT_SIZE_NORMAL) (only applicable when $bMultiple is TRUE)
addSubmit (line 249)

Form submission button

Note the switched value/name parameters!

  • return: html formated submit input field
string addSubmit (string $sValue, [string $sName = null], [array $aAttribs = array()])
  • string $sValue: button name
  • string $sName: submitted key name
  • array $aAttribs: (since 1.5.1) extra attributes
addTextArea (line 282)

Textarea form element.

  • return: html formated text area field
string addTextArea (string $sName, [string $sText = ''], [integer $iCols = 40], [integer $iRows = 10], [array $aAttribs = array()])
  • string $sName: field name
  • string $sText: initial field value (OPTIONAL; default empty)
  • integer $iCols: field width (number of chars) (OPTIONAL; default 40)
  • integer $iRows: field height (number of character rows) (OPTIONAL; default 10)
  • array $aAttribs: (since 1.5.1) extra attributes (OPTIONAL; default empty)
unique_widget_name (line 379)

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

  • return: 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
mixed unique_widget_name (string $base_name, [boolean $return_count = FALSE])
  • string $base_name: The name upon which to base the returned widget name.
  • boolean $return_count: When TRUE, this function will return the last number used to create a widget name for $base_name (OPTIONAL; default = FALSE).

Documentation generated on Wed, 16 Apr 2014 04:17:50 +0200 by phpDocumentor 1.4.3