Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
SwitchableFieldDefinition defines a field that displays alternative fields depending on user choice. For example:
Switch between a plain text editor and a rich text editor.
Authenticated vs. unauthenticated SMTP settings. When the user selects the authenticated option, ask for username and password.
class: info.magnolia.ui.form.field.definition.SwitchableFieldDefinition
Here is a switchable text editor field. It consists of alternative text and rich text fields.
Simple switchable field definition:
form: tabs: - name: tabText label: Text fields: - name: message class: info.magnolia.ui.form.field.definition.SwitchableFieldDefinition label: Message options: - name: plainText label: Plain selected: true value: plainText - name: richText label: Rich value: richText fields: - name: plainText class: info.magnolia.ui.form.field.definition.TextFieldDefinition label: Plain text message rows: 5 - name: richText class: info.magnolia.ui.form.field.definition.RichTextFieldDefinition label: Rich text message height: 200
Node name | Value |
---|---|
form | |
tabs | |
tabText | |
fields | |
message | |
options | |
plainText | |
label | Plain |
selected | true |
value | plainText |
richText | |
label | Rich |
value | richText |
fields | |
plainText | |
class | info.magnolia.ui.form.field.definition.TextFieldDefinition |
label | Plain text message |
rows | 5 |
richText | |
class | info.magnolia.ui.form.field.definition.RichTextFieldDefinition |
label | Rich text message |
height | 200 |
class | info.magnolia.ui.form.field.definition.SwitchableFieldDefinition |
label | Message |
You can use common field properties and the following properties in a switchable field definition:
Properties:
| required Name of parent switchable field. |
| required Options (radio buttons) that allow switching between child fields. You can add more than two options. |
| required Options available for selection. Add one node for each option. The number of options should match the number of child fields. . |
| optional Label displayed next to the radio button. |
| optional When set to Applied only when creating a new item, not for already existing items. |
| optional Value saved to the repository when selected. Should match the name of the corresponding child field node name. |
| required Child fields displayed when the user selects an option. |
| required Child field name. Should match the |
| required Field definition class of the child field. Basic upload field does not work inside a switchable field. |
| required Definition class of the switchable parent field. Use |
| optional , default is Defines the layout of the radio buttons. Set to |
| optional, default is Defines the selection type. Valid values are |
| optional, default is Custom property transformer definition. |
Best practice
When nesting switchable fields, use the delegating transformer classes, DelegatingCompositeFieldTransformer or DelegatingMultiValueFieldTransformer, rather than the other available transformer classes.