Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
Create your own fields when the default fields do not meet your requirements. Magnolia fields are implemented as Vaadin components. Start by looking through the Vaadin sampler, where you will most probably find the required field. If you need a more complex field that is a composition of more than one simple field, look at the composite field or implement a Vaadin CustomField
.
personaSwitcher
is an example of a custom field. Editors can quickly switch between personas while previewing the page.
Required classes
Each field needs the following classes:
Definition class
A definition class defines the field. It typically reads properties from the field definition. The definition class must implement the FieldDefinition interface.
Factory class
A factory class creates and initializes Vaadin fields based on the field definition.
For example, TextFieldFactory creates a text field. It contains logic to react to the definition properties. If the rows
property equals 1 the factory creates a single-line input element. If rows
is more than 1 the factory creates a multiline text area. Factory classes extend AbstractFieldFactory which can handle all common field properties .
Field class
A field class is only needed if you cannot find a single Vaadin field that meets your requirements. Simple fields such as Text do not have a field class - the factory class simply creates the matching Vaadin field directly. However, more complex fields need a field class.
For example, Link is a compound of a text box and a button. Vaadin doesn't provide this combination out of the box, so we need a LinkField class that extends Vaadin CustomField
. The custom field class provides a layout with a text field on the left and a button on the right. It also registers a preview component that displays a thumbnail of the link target if defined.
The Link field is an example that provides all three classes:
info.magnolia.ui.form.field.definition.LinkFieldDefinition
info.magnolia.ui.form.field.factory.LinkFieldFactory
info.magnolia.ui.form.field.LinkField
Registering a field
Any module can register a new field in the fieldTypes
node. Register your field in your own module.
If you add the field to the UI Framework module it becomes globally available. Here is an example how the UI Framework module registers the Text field.
You can configure field types in a YAML definition file inside a light module folder.
definitionClass: info.magnolia.ui.form.field.definition.TextFieldDefinition factoryClass: info.magnolia.ui.form.field.factory.TextFieldFactory
Node name | Value |
---|---|
modules | |
ui-framework | |
fieldTypes | |
text | |
definitionClass | info.magnolia.ui.form.field.definition.TextFieldDefinition |
factoryClass | info.magnolia.ui.form.field.factory.TextFieldFactory |
Using a field in a form
Once the field is registered, add it to a dialog or form by referencing the field definition class in the class
property or by referencing the field alias name in the fieldType
property. See Field definition for more.
If you create a complex field and need to store values in the repository in a specific way, see Transforming field values.