form.select ViewHelper <f:form.select>
¶
This ViewHelper generates a <select>
dropdown list for the use with a form.
Basic usage¶
The most straightforward way is to supply an associative array as the options
parameter.
The array key is used as option key, and the value is used as human-readable name.
Basic usage:
<f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" />
Pre select a value¶
To pre select a value, set value
to the option key which should be selected.
Default value:
<f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" value="visa" />
Generates a dropdown box like above, except that "VISA Card" is selected.
If the select box is a multi-select box multiple="1"
, then "value" can be an array as well.
Custom options and option group rendering¶
Child nodes can be used to create a completely custom set of
<option>
and <optgroup>
tags in a way compatible with the
HMAC generation.
To do so, leave out the options
argument and use child ViewHelpers:
Custom options and optgroup:
<f:form.select name="myproperty">
<f:form.select.option value="1">Option one</f:form.select.option>
<f:form.select.option value="2">Option two</f:form.select.option>
<f:form.select.optgroup>
<f:form.select.option value="3">Grouped option one</f:form.select.option>
<f:form.select.option value="4">Grouped option twi</f:form.select.option>
</f:form.select.optgroup>
</f:form.select>
Note
Do not use vanilla <option>
or <optgroup>
tags!
They will invalidate the HMAC generation!
Usage on domain objects¶
If you want to output domain objects, you can just pass them as array into the options
parameter.
To define what domain object value should be used as option key, use the optionValueField
variable. Same goes for optionLabelField
.
If neither is given, the Identifier (UID/uid) and the __toString()
method are tried as fallbacks.
If the optionValueField
variable is set, the getter named after that value is used to retrieve the option key.
If the optionLabelField
variable is set, the getter named after that value is used to retrieve the option value.
If the prependOptionLabel
variable is set, an option item is added in first position, bearing an empty string or -
if provided, the value of the prependOptionValue
variable as value.
Domain objects:
<f:form.select name="users" options="{userArray}" optionValueField="id" optionLabelField="firstName" />
In the above example, the userArray
is an array of "User" domain objects, with no array key specified.
So, in the above example, the method $user->getId()
is called to
retrieve the key, and $user->getFirstName()
to retrieve the displayed
value of each entry.
The value
property now expects a domain object, and tests for object equivalence.
Arguments¶
additionalAttributes¶
- DataType
- mixed
- Required
- false
- Description
- Additional tag attributes. They will be added directly to the resulting HTML tag.
data¶
- DataType
- mixed
- Required
- false
- Description
- Additional data-* attributes. They will each be added with a "data-" prefix.
aria¶
- DataType
- mixed
- Required
- false
- Description
- Additional aria-* attributes. They will each be added with a "aria-" prefix.
name¶
- DataType
- string
- Required
- false
- Description
- Name of input tag
value¶
- DataType
- mixed
- Required
- false
- Description
- Value of input tag
property¶
- DataType
- string
- Required
- false
- Description
- Name of Object Property. If used in conjunction with <f:form object="...">, the "name" property will be ignored, while "value" can be used to specify a default field value instead of the object property value.
class¶
- DataType
- string
- Required
- false
- Description
- CSS class(es) for this element
dir¶
- DataType
- string
- Required
- false
- Description
- Text direction for this HTML element. Allowed strings: "ltr" (left to right), "rtl" (right to left)
id¶
- DataType
- string
- Required
- false
- Description
- Unique (in this file) identifier for this HTML element.
lang¶
- DataType
- string
- Required
- false
- Description
- Language for this element. Use short names specified in RFC 1766
style¶
- DataType
- string
- Required
- false
- Description
- Individual CSS styles for this element
title¶
- DataType
- string
- Required
- false
- Description
- Tooltip text of element
accesskey¶
- DataType
- string
- Required
- false
- Description
- Keyboard shortcut to access this element
tabindex¶
- DataType
- integer
- Required
- false
- Description
- Specifies the tab order of this element
onclick¶
- DataType
- string
- Required
- false
- Description
- JavaScript evaluated for the onclick event
size¶
- DataType
- string
- Required
- false
- Description
- Size of input field
disabled¶
- DataType
- string
- Required
- false
- Description
- Specifies that the input element should be disabled when the page loads
options¶
- DataType
- mixed
- Required
- false
- Description
- Associative array with internal IDs as key, and the values are displayed in the select box. Can be combined with or replaced by child f:form.select.* nodes.
optionsAfterContent¶
- DataType
- boolean
- Required
- false
- Description
- If true, places auto-generated option tags after those rendered in the tag content. If false, automatic options come first.
optionValueField¶
- DataType
- string
- Required
- false
- Description
- If specified, will call the appropriate getter on each object to determine the value.
optionLabelField¶
- DataType
- string
- Required
- false
- Description
- If specified, will call the appropriate getter on each object to determine the label.
sortByOptionLabel¶
- DataType
- boolean
- Required
- false
- Description
- If true, List will be sorted by label.
selectAllByDefault¶
- DataType
- boolean
- Required
- false
- Description
- If specified options are selected if none was set before.
errorClass¶
- DataType
- string
- Default
- 'f3-form-error'
- Required
- false
- Description
- CSS class to set if there are errors for this ViewHelper
prependOptionLabel¶
- DataType
- string
- Required
- false
- Description
- If specified, will provide an option at first position with the specified label.
prependOptionValue¶
- DataType
- string
- Required
- false
- Description
- If specified, will provide an option at first position with the specified value.
multiple¶
- DataType
- boolean
- Required
- false
- Description
- If set multiple options may be selected.
required¶
- DataType
- boolean
- Required
- false
- Description
- If set no empty value is allowed.