This documentation is still in progress. We are working hard to update all our screenshots to the new Magnolia 6 style. Please bear with us.
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..
Switchable field properties
Simple switchable field definition:
Plain text message
Rich text message
See Referencing fields for further information.
You can use common field properties and the following properties in a switchable field definition:
Name of parent switchable field.
Options (radio buttons) that allow switching between child fields. You can add more than two options.
Options available for selection. Add one node for each option. The number of options should match the number of child fields. .
Label displayed next to the radio button.
When set to
Applied only when creating a new item, not for already existing items.
Value saved to the repository when selected. Should match the name of the corresponding child field node name.
Child fields displayed when the user selects an option.
Child field name. Should match the
Field definition class of the child field. field does not work inside a switchable field.
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.
It can be difficult to configure the correct transformers for advanced fields and especially for fields with complex nesting.
When nesting switchable fields, use delegating field transformers such as the DelegatingCompositeFieldTransformer since normal non-delegating transformers can only handle two nesting levels.
Switchable field and complex nesting
The example configuration below shows the use of the delegating field transformers for a complex nesting scenario where, at the top level, the user has a two-option switch:
The Composite option opens into a composite field with two text fields:
The Multi option opens into a multi field that allows the user to add individual text fields (three are shown):
The field's YAML configuration: