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="...">, "name" and "value" properties will be ignored.

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.