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 Neos: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:
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 Neos: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
Here follows the full configuration for the
ProgrammingLanguageSelect (which is an example taken from the
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 (
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.
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 Neos:Form:presets:[presetName] formElementTypes: 'Neos.FormExample:GenderSelect': formBuilder: editors: # Disable "options" editor options: null
The same distinction between using
the form element type definition directly can also be used to add other elements like
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 Neos:Form:presets:[presetName] formElementTypes: 'Neos.Form:TextMixin': # or any other type here formBuilder: editors: validation: availableValidators: 'Neos.Flow:StringLength': # or any other validator # mark this validator required such that it is always shown. required: true
The same works for Finishers, for example the following configuration makes the EmailFinisher mandatory:
# we are now inside Neos:Form:presets:[presetName] formElementTypes: 'Neos.Form:Form': formBuilder: editors: finishers: availableFinishers: 'Neos.Form:Email': # or any other finisher # mark this finisher required such that it is always shown. required: true
You should now have some receipes at hand on how to modify the Form Builder. Read the next chapter for some more advanced help.