ViewHelper Documentation
form.select
This ViewHelper generates a
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 array value is used as human-readable name.
To pre-select a value, set "value" to the option key which should be selected. If the select box is a multi-select box (multiple="true"), then "value" can be an array as well.
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 (UUID/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 specified - the value of the prependOptionValue variable as value.
In the example below, the userArray is an array of "User" domain objects, with no array key specified. Thus 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.
Translation of select content
The ViewHelper can be given a "translate" argument with configuration on how to translate option labels. The array can have the following keys:
- "by" defines if translation by message id or original label is to be used ("id" or "label")
- "using" defines if the option tag's "value" or "label" should be used as translation input, defaults to "value"
- "locale" defines the locale identifier to use, optional, defaults to current locale
- "source" defines the translation source name, optional, defaults to "Main"
- "package" defines the package key of the translation source, optional, defaults to current package
- "prefix" defines a prefix to use for the message id only works in combination with "by id"
= Examples =
<f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" />
<f:form.select name="paymentOptions" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" value="visa" />
<f:form.select name="users" options="{userArray}" optionValueField="id" optionLabelField="firstName" />
<f:form.select property="salutation" options="{salutations}" prependOptionLabel="- select one -" />
<f:form.select name="paymentOption" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" translate="{by: 'id'}" />
<f:form.select name="paymentOption" options="{payPal: 'PayPal International Services', visa: 'VISA Card'}" translate="{by: 'id', prefix: 'shop.paymentOptions.'}" />
Arguments
- additionalAttributes
- data
- name
- value
- property
- class
- dir
- id
- lang
- style
- title
- accesskey
- tabindex
- onclick
- multiple
- size
- disabled
- required
- options
- optionValueField
- optionLabelField
- sortByOptionLabel
- selectAllByDefault
- errorClass
- translate
- prependOptionLabel
- prependOptionValue
additionalAttributes anySimpleType
Additional tag attributes. They will be added directly to the resulting HTML tag.
data anySimpleType
Additional data-* attributes. They will each be added with a "data-" prefix.
name string
Name of input tag
value anySimpleType
Value of input tag
property string
Name of Object Property. If used in conjunction with <f:form object="...">, "name" and "value" properties will be ignored.
class string
CSS class(es) for this element
dir string
Text direction for this HTML element. Allowed strings: "ltr" (left to right), "rtl" (right to left)
id string
Unique (in this file) identifier for this HTML element.
lang string
Language for this element. Use short names specified in RFC 1766
style string
Individual CSS styles for this element
title string
Tooltip text of element
accesskey string
Keyboard shortcut to access this element
tabindex integer
Specifies the tab order of this element
onclick string
JavaScript evaluated for the onclick event
multiple string
if set, multiple select field
size string
Size of input field
disabled boolean
Specifies that the input element should be disabled when the page loads
required boolean
Specifies that the select element requires at least one selected option
options anySimpleType
Associative array with internal IDs as key, and the values are displayed in the select box
optionValueField string
If specified, will call the appropriate getter on each object to determine the value.
optionLabelField string
If specified, will call the appropriate getter on each object to determine the label.
sortByOptionLabel boolean
If true, List will be sorted by label.
selectAllByDefault boolean
If specified options are selected if none was set before.
errorClass string
CSS class to set if there are errors for this ViewHelper
translate anySimpleType
Configures translation of ViewHelper output.
prependOptionLabel string
If specified, will provide an option at first position with the specified label.
prependOptionValue string
If specified, will provide an option at first position with the specified value. This argument is only respected if prependOptionLabel is set.