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.
private Request|null $request The Request instance.

Methods

__construct(Application $app)

Initialize the instance.

setRequest(Request $request)

Set the request instance.

getRequest()

No description

URLInterface
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($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.

$html
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.

$html
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

setRequest(Request $request)

Set the request instance.

Parameters

Request $request

protected Request getRequest()

Return Value

Request

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

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

Parameters

string $action
string $task

Return Value

URLInterface

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($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

$key

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

$html 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'

Return Value

$html

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: - 'noCountryText': the text to be displayed when no country is selected - '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'

$html 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'

Return Value

$html

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