class Form (View source)

Helpful functions for working with forms. Includes HTML input tags and the like.

\@package Helpers

Properties

protected int $radioIndex

Internal counter used to generate unique IDs for radio inputs with the same name.

protected int $selectIndex

Internal counter used to generate unique IDs for select inputs with the same name.

protected Application $app

The Application instance.

protected Text $th

The text service instance.

protected Arrays $ah

Arrays helper instance.

Methods

__construct(Application $app)

Initialize the instance.

action(string $action, string $task = null)

Returns an action suitable for including in a form action property.

string
submit(string $key, string $value, array $miscFields = [], string $additionalClasses = '')

Creates a submit button.

string
button(string $key, string $value, array $miscFields = [], string $additionalClasses = '')

Creates a button.

string
label(string $forFieldID, string $innerHTML, array $miscFields = [])

Creates a label tag.

string
file(string $key, array $miscFields = [])

Creates a file input element.

string
hidden(string $key, string $value = null, array $miscFields = [])

Creates a hidden form field.

string
checkbox(string $key, string $value, string $isChecked = false, array $miscFields = [])

Generates a checkbox.

string
textarea(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Creates a textarea field.

string
radio(string $key, string $value, string|array $checkedValueOrMiscFields = '', array $miscFields = [])

Generates a radio button.

false|array|string
getRequestValue(string $key)

Checks the request (first POST then GET) based on the key passed.

string
text(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a text input field.

string
number(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a number input field.

string
email(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders an email input field.

string
telephone(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a telephone input field.

string
url(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a URL input field.

string
search(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a search input field.

select(string $key, array $optionValues, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a select field.

selectCountry(string $key, string $selectedCountryCode = '', array $configuration = [], array $miscFields = [])

Renders a select menu to choose a Country.

selectMultiple(string $key, array $optionValues, array|string $defaultValues = false, array $miscFields = [])

Renders a multiple select box.

string
password(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a password input field.

string
getAutocompletionDisabler()

Generates HTML code that can be added at the beginning of a form to disable username/password autocompletion.

false|array|string
processRequestValue(string $key, string $type = 'post')

Checks the request based on the key passed.

string
inputType(string $key, string $type, string|array $valueOrMiscFields, array $miscFields)

Internal function that creates an element of type $type. Handles the messiness of evaluating $valueOrMiscFields. Assigns a default class of ccm-input-$type.

string
parseMiscFields(string $defaultClass, array $attributes)

Create an HTML fragment of attribute values, merging any CSS class names as necessary.

Details

__construct(Application $app)

Initialize the instance.

Parameters

Application $app

action(string $action, string $task = null)

Returns an action suitable for including in a form action property.

Parameters

string $action
string $task

string submit(string $key, string $value, array $miscFields = [], string $additionalClasses = '')

Creates a submit button.

Parameters

string $key

the name/id of the element

string $value

The value of the element

array $miscFields

additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

string $additionalClasses

list of additional space-separated CSS class names

Return Value

string

string button(string $key, string $value, array $miscFields = [], string $additionalClasses = '')

Creates a button.

Parameters

string $key

the name/id of the element

string $value

The value of the element

array $miscFields

additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

string $additionalClasses

list of additional space-separated CSS class names

Return Value

string

string label(string $forFieldID, string $innerHTML, array $miscFields = [])

Creates a label tag.

Parameters

string $forFieldID

the id of the associated element

string $innerHTML

the inner html of the label

array $miscFields

additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string file(string $key, array $miscFields = [])

Creates a file input element.

Parameters

string $key

the name/id of the element

array $miscFields

additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string hidden(string $key, string $value = null, array $miscFields = [])

Creates a hidden form field.

Parameters

string $key

the name/id of the element

string $value

the value of the element (overriden if we received some data in POST or GET)

array $miscFields

additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string checkbox(string $key, string $value, string $isChecked = false, array $miscFields = [])

Generates a checkbox.

Parameters

string $key

The name/id of the element. It should end with '[]' if it's to return an array on submit.

string $value

String value sent to server, if checkbox is checked, on submit

string $isChecked

"Checked" value (subject to be overridden by $_REQUEST). Checkbox is checked if value is true (string). Note that 'false' (string) evaluates to true (boolean)!

array $miscFields

additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string textarea(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Creates a textarea field.

Parameters

string $key

the name/id of the element

string|array $valueOrMiscFields

the value of the element or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string radio(string $key, string $value, string|array $checkedValueOrMiscFields = '', array $miscFields = [])

Generates a radio button.

Parameters

string $key

the name of the element (its id will start with $key but will have a progressive unique number added)

string $value

the value of the radio button

string|array $checkedValueOrMiscFields

the value of the element (if it should be initially checked) or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $checkedValueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

false|array|string getRequestValue(string $key)

Checks the request (first POST then GET) based on the key passed.

If $key denotes an array (eg akID[34]['value']) we'll turn the key into arrays if the key has text versions of [ and ] in it If the result is a string, it'll be escaped (with htmlspecialchars).

Parameters

string $key

the name of the field to be checked

Return Value

false|array|string

returns an array if $key denotes an array and we received that data, a string if $key is the name of a received data, false if $key is not found in the received data

string text(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a text input field.

Parameters

string $key

the name/id of the element

string|array $valueOrMiscFields

the value of the element or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string number(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a number input field.

Parameters

string $key

the name/id of the element

string|array $valueOrMiscFields

the value of the element or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string email(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders an email input field.

Parameters

string $key

the name/id of the element

string|array $valueOrMiscFields

the value of the element or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string telephone(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a telephone input field.

Parameters

string $key

the name/id of the element

string|array $valueOrMiscFields

the value of the element or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string url(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a URL input field.

Parameters

string $key

the name/id of the element

string|array $valueOrMiscFields

the value of the element or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

Renders a search input field.

Parameters

string $key

the name/id of the element

string|array $valueOrMiscFields

the value of the element or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

select(string $key, array $optionValues, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a select field.

Parameters

string $key

The name of the element. If $key denotes an array, the ID will start with $key but will have a progressive unique number added; if $key does not denotes an array, the ID attribute will be $key.

array $optionValues

an associative array of key => display

string|array $valueOrMiscFields

the value of the field to be selected or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

selectCountry(string $key, string $selectedCountryCode = '', array $configuration = [], array $miscFields = [])

Renders a select menu to choose a Country.

Parameters

string $key

The name of the element. If $key denotes an array, the ID will start with $key but will have a progressive unique number added; if $key does not denotes an array, the ID attribute will be $key.

string $selectedCountryCode

the code of the Country to be initially selected

array $configuration

Configuration options. Supported keys are:

  • 'required': do users must choose a Country?
  • 'allowedCountries': an array containing a list of acceptable Country codes. If not set, all the countries will be selectable.
  • 'linkStateProvinceField': set to true to look for text fields that have a "data-countryfield" attribute with the same value as this Country field name (updating the Country select will automatically update the State/Province list).
array $miscFields

Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

selectMultiple(string $key, array $optionValues, array|string $defaultValues = false, array $miscFields = [])

Renders a multiple select box.

Parameters

string $key

The ID of the element. The name attribute will be $key followed by '[].

array $optionValues

Hash array with name/value as the select's option value/text

array|string $defaultValues

Default value(s) which match with the option values; overridden by $_REQUEST

array $miscFields

additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

string password(string $key, string|array $valueOrMiscFields = '', array $miscFields = [])

Renders a password input field.

Parameters

string $key

the name/id of the element

string|array $valueOrMiscFields

the value of the element or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

string getAutocompletionDisabler()

Generates HTML code that can be added at the beginning of a form to disable username/password autocompletion.

Return Value

string

protected false|array|string processRequestValue(string $key, string $type = 'post')

Checks the request based on the key passed.

If $key denotes an array (eg akID[34]['value']) we'll turn the key into arrays if the key has text versions of [ and ] in it If the result is a string, it'll be escaped (with htmlspecialchars).

Parameters

string $key

the name of the field to be checked

string $type

'post' to check in POST data, other values to check in GET data

Return Value

false|array|string

returns an array if $key denotes an array and we received that data, a string if $key is the name of a received data, false if $key is not found in the received data

protected string inputType(string $key, string $type, string|array $valueOrMiscFields, array $miscFields)

Internal function that creates an element of type $type. Handles the messiness of evaluating $valueOrMiscFields. Assigns a default class of ccm-input-$type.

Parameters

string $key

the name/id of the element

string $type

Accepted value for HTML attribute "type"

string|array $valueOrMiscFields

the value of the element or an array with additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

array $miscFields

(used if $valueOrMiscFields is not an array) Additional fields appended to the element (a hash array of attributes name => value), possibly including 'class'

Return Value

string

protected string parseMiscFields(string $defaultClass, array $attributes)

Create an HTML fragment of attribute values, merging any CSS class names as necessary.

Parameters

string $defaultClass

Default CSS class name

array $attributes

a hash array of attributes (name => value), possibly including 'class'

Return Value

string

A fragment of attributes suitable to put inside of an HTML tag