Form.select ViewHelper <f:form.select>

This ViewHelper generates a <select> dropdown list for the use with a form.

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

Table of contents

Select field with hardcoded options

Using the options parameter, you can pass a hardcoded array to the form.select ViewHelper.

The key of that array is used as option key, and the value is used as human-readable name.

packages/my_extension/Resources/Private/Templates/User/GenderForm.html 
<f:form action="selectGender">
    <f:form.select name="gender" options="{1: 'female', 2: 'male', 3: 'diverse'}" />
    <f:form.submit value="Submit"/>
</f:form>
Copied!

The argument will have the key of the chosen entry as value.

packages/my_extension/Classes/Controller/UserController.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class UserController extends ActionController
{
    public function genderFormAction(): ResponseInterface
    {
        return $this->htmlResponse();
    }
    public function selectGenderAction(int $gender): ResponseInterface
    {
        // do something
        return $this->redirect('show');
    }
}
Copied!

Preselected field with options supplied by the controller

Most options will be supplied by the controller. You can pass an associative array with the options to the view:

packages/my_extension/Resources/Private/Templates/User/PaymentForm.html 
<f:form action="selectPayment">
    <f:form.select name="payment" options="{paymentOptions}" value="{myPayment}" />
    <f:form.submit value="Submit"/>
</f:form>
Copied!

The argument for the select field will have the key of the chosen entry as value.

packages/my_extension/Classes/Controller/UserController.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class UserController extends ActionController
{
    public function paymentFormAction(): ResponseInterface
    {
        $paymentOptions =
            ['payPal' => 'PayPal International Services', 'visa' => 'VISA Card'];
        $this->view->assign('paymentOptions', $paymentOptions);
        $this->view->assign('myPayment', 'visa');
        return $this->htmlResponse();
    }
    public function selectPaymentAction(string $payment): ResponseInterface
    {
        // do something
        return $this->redirect('show');
    }
}
Copied!

To pre-select a value, use the argument value.

Select field for selecting (persisted) models

Consider we have the payment options from the previous example in the database and in an Extbase model:

packages/my_extension/Classes/Domain/Model/PaymentMethod.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Domain\Model;

use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;

class PaymentMethod extends AbstractEntity implements \Stringable
{
    protected string $title;
    protected string $paymentIdentifier;

    // Getters and setters

    // If the model implement the __toString() method
    // The result of that method is displayed in the select form
    public function __toString(): string
    {
        return $this->title;
    }
}
Copied!

In the controller we can get all payment methods from the Repository now and pass it to the view as variable:

packages/my_extension/Classes/Controller/UserController.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class UserController extends ActionController
{
    public function __construct(
        protected readonly PaymentMethodRepository $paymentMethodRepository,
    ) {}

    public function paymentFormAction(): ResponseInterface
    {
        $paymentOptions = $this->paymentMethodRepository->findAll();
        $this->view->assign('paymentOptions', $paymentOptions);
        $this->view->assign('myPayment', 'visa');
        return $this->htmlResponse();
    }
    public function selectPaymentAction(PaymentMethod $payment): ResponseInterface
    {
        // do something
        return $this->redirect('show');
    }
}
Copied!

The Fluid template can be left unchanged even though we are dealing with a different data source:

packages/my_extension/Resources/Private/Templates/User/PaymentForm.html 
<f:form action="selectPayment">
    <f:form.select name="payment" options="{paymentOptions}" value="{myPayment}" />
    <f:form.submit value="Submit"/>
</f:form>
Copied!

When the form gets submitted, the UID of the chosen model appears in the request data. Extbase will then map that uid back to the model for you.

The ViewHelper will then use the model's UID as data submitted in the form and the result of method __toString() as display text.

optionLabelField: Define another property of the model for the option label

If the model to be displayed has no __toString() method or you want to display the content of a different field, use option optionLabelField

<f:form.select name="payment" value="{myPayment}"
    options="{paymentOptions}" optionLabelField="someLabel"/>
Copied!

The options may contain an array or anything else Traversable including

optionValueField: Define another property of the model as value

If you are dealing with non-persisted models or Data-Transfer-Objects (DTO) there is no valid identifier that could be used to automatically map the user's selection in your controller. In this case, you must provide the name of the field to be used to identify the object:

<f:form.select name="payment" value="{myPayment}"
    options="{paymentOptions}" optionValueField="paymentIdentifier"/>
Copied!

The controller action will then be called with the content of that field:

// Variable $payment contains the paymentIdentifier from the model
public function selectPaymentAction(String $payment): ResponseInterface
Copied!

Binding the select field to an object property

When the surrounding <f:form> uses Property mapping we can also map the selected option to the model:

packages/my_extension/Resources/Private/Templates/User/PaymentForm.html 
<f:form action="selectPreferredPayment" object="{user}" objectName="user">
    <f:form.select options="{user.availablePaymentOptions}"
                   property="preferredPayment"
    />
    <f:form.submit value="Submit"/>
</f:form>
Copied!

The user model could have the following fields

packages/my_extension/Classes/Domain/Model/User.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Domain\Model\PaymentMethod;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;

class User extends AbstractEntity
{
    //Other fields
    protected ?PaymentMethod $preferredPayment;
    /** @var ObjectStorage<PaymentMethod>  */
    protected ObjectStorage $availablePaymentOptions;

    // initialize method, getters and setters
}
Copied!

The controller action will then be called with the user object:

public function selectPreferredPaymentAction(User $user): ResponseInterface
Copied!

Working with options and option groups

Form.select.option ViewHelper <f:form.select.option>

Adds custom <option> tags inside an <f:form.select>.

Go to the source code of this ViewHelper: Form\Select\OptionViewHelper.php (GitHub).

The <f:form.select.option> ViewHelper can be used to create a completely <f:form.select.option> <option> tags in a way compatible with the HMAC generation. To do so, leave out the options argument and use child ViewHelpers:

<f:form.select name="myproperty">
  <f:form.select.option value="1">Option one</f:form.select.option>
  <f:form.select.option value="2" selected="1">Option two</f:form.select.option>
</f:form.select>
Copied!

Form.select.optgroup ViewHelper <f:form.select.optgroup>

Adds custom <optgroup> tags inside an <f:form.select>, supports further child <f:form.select.option> tags.

Go to the source code of this ViewHelper: Form\Select\OptgroupViewHelper.php (GitHub).

The <f:form.select.option> can be grouped with the <f:form.select.optgroup> to produce <optgroup> in the HTML output.

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

Using an "Please select an option" placeholder

In HTML, the <select> element always selects the first option, if nothing else is selected. If the field is mandatory and the user should be forced to make a selection or if an empty value should be possible, you need an empty option as first option. You can use the argument prependOptionLabel to set a label for this object. The value of the option will be an empty string. If you need another value, for example 0 because you are expecting an integer, you can use prependOptionValue.

<f:form.select options="{user.availablePaymentOptions}"
               property="preferredPayment"
               prependOptionLabel="Ask me every time!"
               prependOptionValue="ask"
/>
Copied!

You can achieve the same effect by combining the options argument with one (or several) <form.select.option> <f:form.select.option>:

<f:form.select options="{user.availablePaymentOptions}"
               property="preferredPayment"
               optionsAfterContent="true"
               required="1"
>
   <f:form.select.option value="">Please Chose *</f:form.select.option>
   <f:form.select.option value="ask">Ask me every time!</f:form.select.option>
</f:form.select>
Copied!

It is possible to put the additional options last and combine the two:

<f:form.select options="{user.availablePaymentOptions}"
               property="preferredPayment"
               prependOptionLabel="Please Chose *"
               required="1"
>
   <f:form.select.option value="ask">Ask me every time!</f:form.select.option>
</f:form.select>
Copied!

Arguments of the Form.select ViewHelper

additionalAttributes

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

aria

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

data

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

errorClass

errorClass
Type
string
Default
'f3-form-error'
CSS class to set if there are errors for this ViewHelper

multiple

multiple
Type
boolean
Default
false
If set multiple options may be selected.

name

name
Type
string
Name of input tag

optionLabelField

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

optionValueField

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

options

options
Type
array
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

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

prependOptionLabel

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

prependOptionValue

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

property

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.

required

required
Type
boolean
Default
false
If set no empty value is allowed.

selectAllByDefault

selectAllByDefault
Type
boolean
Default
false
If specified options are selected if none was set before.

sortByOptionLabel

sortByOptionLabel
Type
boolean
Default
false
If true, List will be sorted by label.

value

value
Type
mixed
Value of input tag

Arguments of the Form.select.option ViewHelper

additionalAttributes

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

data

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

selected

selected
Type
boolean
If set, overrides automatic detection of selected state for this option.

value

value
Type
mixed
Value to be inserted in HTML tag - must be convertible to string!

Arguments of the Form.select.optgroup ViewHelper

additionalAttributes

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

data

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

disabled

disabled
Type
boolean
Default
false
If true, option group is rendered as disabled