Configuring Form Builder¶
After this guide, you will have learned how to Configure the Form Builder through settings
Adding a New Form Element Inside “Create Elements”¶
Let’s say you have created your form element, and want to make it available inside the Form Builder. For that, you need some YAML configuration which looks as follows:
# we are now inside TYPO3:Form:presets:[presetName]
formElementTypes:
'Your.Package:YourFormElement':
# the definitions for your form element
formBuilder:
label: 'Your New Form Element'
group: custom
sorting: 200
To determine whether a form element is visible in the Form Builder, you must set formBuilder:group
to a valid group. A form element group is used to visually group the available form elements together. In the default profile, the following groups are configured:
- input
- select
- custom
- container
The label
is – as you might expect – the human-readable label, while the sorting
determines the ordering of form elements inside their form element group.
Creating a New Form Element Group¶
All form element groups are defined inside formElementGroups
inside the preset, so that’s how you can add a new group:
# we are now inside TYPO3:Form:presets:[presetName]
formElementGroups:
specialCustom:
sorting: 500
label: 'My special custom group'
For each group, you need to specify a human-readable label
, and the sorting
(which determines the ordering of the groups).
Setting Default Values for Form Elements¶
When a form element is created, you can define some default values which are directly set on the form element. As an example, let’s imagine you want to build a ProgrammingLanguageSelect
where the user can choose his favorite programming language.
In this case, we want to define some default programming languages, but the integrator who builds the form should be able to add custom options as well. These default options can be set in Settings.yaml
using the formBuilder:predefinedDefaults
key.
Here follows the full configuration for the ProgrammingLanguageSelect
(which is an example taken from the TYPO3.FormExample
package):
# we are now inside TYPO3:Form:presets:[presetName]
formElementTypes:
'TYPO3.FormExample:ProgrammingLanguageSelect':
superTypes: ['TYPO3.Form:SingleSelectRadiobuttons']
renderingOptions:
templatePathPattern: 'resource://TYPO3.Form/Private/Form/SingleSelectRadiobuttons.html'
# here follow the form builder specific options
formBuilder:
group: custom
label: 'Programming Language Select'
# we now set some defaults which are applied once the form element is inserted to the form
predefinedDefaults:
properties:
options:
0:
_key: 'php'
_value: 'PHP'
1:
_key: 'java'
_value: 'Java etc'
2:
_key: 'js'
_value: 'JavaScript'
Contrasting Use Case: Gender Selection¶
Inside Creating a new form element, we have implemented a special Gender Select. Let’s think a second about the differences between the Gender Select and the Programming Language Select examples:
For a Gender select field, the integrator using the form builder does not need to set any options for this form element, as the available choices (Female
and Male
) are predefined inside the form element template.
In the case of the programming language select, we only want to set some sensible defaults for the integrator, but want him to be able to adjust the values.
Choosing which strategy to use depends mostly on the expected usage patterns:
- In the gender select example, if a new option is added to the list afterwards, this will directly be reflected in all forms which use this input field.
- If you use
predefinedDefaults
, changing these will be only applied to new elements, but not to already existing elements.
Note
In order to make the gender selection work nicely with the Form Builder,
we should disable the options
editor as follows (as the options should not be editable by the implementor):
# we are now inside TYPO3:Form:presets:[presetName] formElementTypes: 'TYPO3.FormExample:GenderSelect': formBuilder: editors: # Disable "options" editor options: null
Tip
The same distinction between using formBuilder:predefinedDefaults
and
the form element type definition directly can also be used to add other elements like
Validators
or Finishers
.
Marking Validators and Finishers As Required¶
Sometimes, you want to simplify the Form Builder User Interface and make certain options easier for your users. A frequent use-case is that you want that a certain validator, like the StringLength
validator, is always shown in the user interface as it is very often used.
This can be configured as follows:
# we are now inside TYPO3:Form:presets:[presetName]
formElementTypes:
'TYPO3.Form:TextMixin': # or any other type here
formBuilder:
editors:
validation:
availableValidators:
'TYPO3.Flow:StringLength': # or any other validator
# mark this validator required such that it is always shown.
required: true
Finishers¶
The same works for Finishers, for example the following configuration makes the EmailFinisher mandatory:
# we are now inside TYPO3:Form:presets:[presetName]
formElementTypes:
'TYPO3.Form:Form':
formBuilder:
editors:
finishers:
availableFinishers:
'TYPO3.Form:Email': # or any other finisher
# mark this finisher required such that it is always shown.
required: true
Finishing Up¶
You should now have some receipes at hand on how to modify the Form Builder. Read the next chapter for some more advanced help.