class Form (View source)

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

\@package Helpers

Traits

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

void
handleRequiredFeatures(mixed $controller, Theme $theme)

Given a block or page controller that we're rendering, we request all the features required by that block controller and then add them to the page's header/footer via requireAsset, if they're not already provided by the theme (which we check via getThemeSupportedFeatures)

void
requireFeaturesIfNotPresentInTheme(array $features, Theme $theme)

Requires one or more features if not present in theme.

__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, $value, $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|int $value, string|array|bool|int $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, int|string|array<string,mixed> $valueOrMiscFields = '', array<string,mixed> $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.

string
__call($name, $args)

Renders any previously unspecified input field type. Allows for adaptive update to any new HTML input types that are not covered by explicit methods. Browsers will either handle the specific input type or fallback to a text input.

select(string $key, array $optionValues, string|array|int $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) deprecated

No description

string
serializeMiscFields(string $defaultClass, array $attributes, array $skipFields = ['name', 'id'])

No description

array
extractNameAndID(string $key, array $miscFields)

Extract the value of the name and the id attributes.

string
buildNameAndID(string $key, array $miscFields)

Generate the HTML code containing the name and the id attributes (if any).

Details

protected void handleRequiredFeatures(mixed $controller, Theme $theme)

Given a block or page controller that we're rendering, we request all the features required by that block controller and then add them to the page's header/footer via requireAsset, if they're not already provided by the theme (which we check via getThemeSupportedFeatures)

Parameters

mixed $controller
Theme $theme

Return Value

void

protected void requireFeaturesIfNotPresentInTheme(array $features, Theme $theme)

Requires one or more features if not present in theme.

Parameters

array $features
Theme $theme

Return Value

void

__construct(Application $app)

Initialize the instance.

Parameters

Application $app

setRequest(Request $request)

Set the request instance.

Parameters

Request $request

protected Request getRequest()

No description

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

Return Value

string

string checkbox(string $key, $value, $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.

$value
$isChecked
array $miscFields

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

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', 'id', and 'name'

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', 'id', and 'name'

Return Value

string

string radio(string $key, string|int $value, string|array|bool|int $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|int $value

the value of the radio button

string|array|bool|int $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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

Return Value

string

string number(string $key, int|string|array<string,mixed> $valueOrMiscFields = '', array<string,mixed> $miscFields = [])

Renders a number input field.

Parameters

string $key

the name/id of the element

int|string|array<string,mixed> $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', 'id', and 'name'

array<string,mixed> $miscFields

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

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

Return Value

string

string __call($name, $args)

Renders any previously unspecified input field type. Allows for adaptive update to any new HTML input types that are not covered by explicit methods. Browsers will either handle the specific input type or fallback to a text input.

Parameters

$name
$args

Return Value

string

select(string $key, array $optionValues, string|array|int $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|int $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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

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', 'id', and 'name'

Return Value

string

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

deprecated Use serializeMiscFields

No description

Parameters

string $defaultClass
array $attributes

Return Value

string

protected string serializeMiscFields(string $defaultClass, array $attributes, array $skipFields = ['name', 'id'])

No description

Parameters

string $defaultClass

Default CSS class name

array $attributes

a key/value array of attributes (name => value), possibly including 'class' or 'classes'

array $skipFields

names of fields not to be serialized

Return Value

string

protected array extractNameAndID(string $key, array $miscFields)

Extract the value of the name and the id attributes.

Parameters

string $key

to be used if $miscFields does not contain the 'name' or the 'id' attribute.

array $miscFields

an array with the element attributes (key/value pair).

Return Value

array

first element is the value of the name attributes, second element is the value of the id attribute.

protected string buildNameAndID(string $key, array $miscFields)

Generate the HTML code containing the name and the id attributes (if any).

Parameters

string $key

to be used if $miscFields does not contain the 'id' or the 'name' attribute.

array $miscFields

an array with the element attributes (key/value pair).

Return Value

string

If not empty, the result will start with a space