The 5.7 branch of Magnolia reached End-of-Life on December 31, 2023, as specified in our End-of-life policy. This means the 5.7 branch is no longer maintained or supported. Please upgrade to the latest Magnolia release. By upgrading, you will get the latest release of Magnolia featuring significant improvements to the author and developer experience. For a successful upgrade, please consult our Magnolia 6.2 documentation. If you need help, please contact info@magnolia-cms.com.
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.
- In a shop, switch between separate shipping and billing addresses or using the same address for both..
Class: info.magnolia.ui.form.field.definition.SwitchableFieldDefinition
Here is a switchable text editor field. It consists of alternative text and rich text fields.
Switchable field properties
Simple switchable field definition:
form: tabs: - name: tabText label: Text fields: - name: message fieldType: switchable label: Message options: - name: plainText label: Plain selected: true value: plainText - name: richText label: Rich value: richText fields: - name: plainText fieldType: text label: Plain text message rows: 5 - name: richText fieldType: richText 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 | |
fieldType | text |
label | Plain text message |
rows | 5 |
richText | |
fieldType | richText |
label | Rich text message |
height | 200 |
fieldType | switchable |
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.