**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 =
/**
* @test
*/
public function prependedOptionLabelIsTranslatedIfTranslateArgumentIsSet()
{
$this->tagBuilder->expects($this->once())->method('addAttribute')->with('name', 'myName');
$this->viewHelper->expects($this->once())->method('registerFieldNameForFormTokenGeneration')->with('myName');
$this->tagBuilder->expects($this->once())->method('setContent')->with('<option value="">translated label</option>' . chr(10));
$this->tagBuilder->expects($this->once())->method('render');
$this->arguments['options'] = array();
$this->arguments['name'] = 'myName';
$this->arguments['prependOptionLabel'] = 'select';
$this->arguments['translate'] = array('by' => 'id', 'using' => 'label');
$mockTranslator = $this->createMock(\Neos\Flow\I18n\Translator::class);
$mockTranslator->expects($this->at(0))->method('translateById')->with('select', array(), null, null, 'Main', '')->will($this->returnValue('translated label'));
$this->viewHelper->_set('translator', $mockTranslator);
$this->injectDependenciesIntoViewHelper($this->viewHelper);
$this->viewHelper->initialize();
$this->viewHelper->render();
}