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'}" />
Copied!

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" />
Copied!

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>
Copied!

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" />
Copied!

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.

Source code

Go to the source code of this ViewHelper: SelectViewHelper.php (GitHub).

Arguments

The following arguments are available for <f:form.select>:

Name Type Default
additionalAttributes
 mixed
data
 mixed
aria
 mixed
name
 string
value
 mixed
property
 string
class
 string
dir
 string
id
 string
lang
 string
style
 string
title
 string
accesskey
 string
tabindex
 integer
onclick
 string
size
 string
disabled
 string
options
 mixed
optionsAfterContent
 boolean
optionValueField
 string
optionLabelField
 string
sortByOptionLabel
 boolean
selectAllByDefault
 boolean
errorClass
 string 'f3-form-error'
prependOptionLabel
 string
prependOptionValue
 string
multiple
 boolean
required
 boolean
additionalAttributes
Type
mixed

Additional tag attributes. They will be added directly to the resulting HTML tag.

data
Type
mixed

Additional data-* attributes. They will each be added with a "data-" prefix.

aria
Type
mixed

Additional aria-* attributes. They will each be added with a "aria-" prefix.

name
Type
string

Name of input tag

value
Type
mixed

Value of input tag

property
Type
string

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
Type
string

CSS class(es) for this element

dir
Type
string

Text direction for this HTML element. Allowed strings: "ltr" (left to right), "rtl" (right to left)

id
Type
string

Unique (in this file) identifier for this HTML element.

lang
Type
string

Language for this element. Use short names specified in RFC 1766

style
Type
string

Individual CSS styles for this element

title
Type
string

Tooltip text of element

accesskey
Type
string

Keyboard shortcut to access this element

tabindex
Type
integer

Specifies the tab order of this element

onclick
Type
string

JavaScript evaluated for the onclick event

size
Type
string

Size of input field

disabled
Type
string

Specifies that the input element should be disabled when the page loads

options
Type
mixed

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
Type
boolean

If true, places auto-generated option tags after those rendered in the tag content. If false, automatic options come first.

optionValueField
Type
string

If specified, will call the appropriate getter on each object to determine the value.

optionLabelField
Type
string

If specified, will call the appropriate getter on each object to determine the label.

sortByOptionLabel
Type
boolean

If true, List will be sorted by label.

selectAllByDefault
Type
boolean

If specified options are selected if none was set before.

errorClass
Type
string
Default
'f3-form-error'

CSS class to set if there are errors for this ViewHelper

prependOptionLabel
Type
string

If specified, will provide an option at first position with the specified label.

prependOptionValue
Type
string

If specified, will provide an option at first position with the specified value.

multiple
Type
boolean

If set multiple options may be selected.

required
Type
boolean

If set no empty value is allowed.