1. class
  2. Concrete
  3. \
  4. Core
  5. \
  6. Form
  7. \
  8. Service
  9. \
  10. Form

Form

class Form (View source)

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

\@package Helpers

Traits

HandleRequiredFeaturesTrait

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)

from  HandleRequiredFeaturesTrait
void
requireFeaturesIfNotPresentInTheme(array $features, Theme $theme)

Requires one or more features if not present in theme.

from  HandleRequiredFeaturesTrait
__construct(Application $app)

Initialize the instance.

setRequest(Request $request)

Set the request instance.

Request
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

in HandleRequiredFeaturesTrait at line 22
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

in HandleRequiredFeaturesTrait at line 35
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

at line 78
__construct(Application $app)

Initialize the instance.

Parameters

Application $app

at line 90
setRequest(Request $request)

Set the request instance.

Parameters

Request $request

at line 98
protected Request getRequest()

No description

Return Value

Request

at line 115
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

at line 130
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

at line 146
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

at line 161
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

at line 185
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

at line 200
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

at line 224
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

at line 264
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

at line 291
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

at line 337
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

at line 356
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

at line 370
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

at line 384
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

at line 398
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

at line 412
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

at line 442
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

at line 463
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'

at line 532
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'

at line 634
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'

at line 699
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

at line 709
string getAutocompletionDisabler()

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

Return Value

string

at line 750
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

at line 781
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

at line 808
protected string parseMiscFields(string $defaultClass, array $attributes) deprecated

deprecated Use serializeMiscFields

No description

Parameters

string $defaultClass
array $attributes

Return Value

string

at line 820
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

at line 862
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.

at line 878
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