Field definition - 5 UI
Deprecated
This field definition has been deprecated since Magnolia 6.0. It is part of the Magnolia 5 UI framework. For the updated implementation, see Field definition for Magnolia 6 UI instead. |
A field is an HTML form element that allows a user to perform a task such as enter text, upload an image or select a date. Magnolia ships with a number of fields that should fulfill most needs.
Example
This form has four text fields and one checkbox field:
To add a field on your
form,
define the field inside a tab (see example below). At minimum, a field
definition must contain a class
or a fieldType
property which tells
Magnolia what type of field it should render. Set the property value to
a valid field definition class name (for class
) or
to a valid field alias name (for fieldType
). All fields support
further common properties for defining
things such as labels and descriptions.
form:
tabs:
- name: tabMain
label: Text
fields:
- name: title
fieldType: text
label: pages.pageProperties.title.label
description: pages.pageProperties.title.description
i18n: true
required: true
type: string
Common field properties
You can use these properties with any field unless specified otherwise.
Property | Description | ||
---|---|---|---|
|
required Defines the field type via either a field alias name or a fully-qualified field definition class name. See Field definition: Field types. To check the correct form of the name, use the Definitions app. |
||
|
optional Pre-filled default value displayed in the field. The value can be overwritten by the user. Use alphanumeric characters.
|
||
|
optional Help text displayed when the user clicks the help icon. The value can be literal or retrieved from the message bundle with a key. Use alphanumeric characters in literal values. Not applicable to the static field. |
||
|
optional, default is Enables i18n
authoring support which allows editors to write foreign-language or
regionally targeted content. A two-letter language identifier (en, de,
fr etc.) is displayed on controls where |
||
|
optional, default is the message bundle defined in the dialog definition_ Message bundle such
as |
||
|
optional Field label displayed to editors. The value can be literal such as
If you do not provide the property, Magnolia will fall back to a generated i18n key and display the key in the UI. If you do not want a label at all, define the property and set its value
to a blank space such as |
||
|
optional, default is the name of the field’s parent node_ Name of the node where the value is saved. The name |
||
|
|||
|
optional, default is Makes the field uneditable. Adding this property has the same effect as creating a static field. |
||
|
optional, default is Makes the field required (mandatory). An asterisk is displayed next to the field label. See also Checking for null values. |
||
|
optional, default is Error message displayed when required is true and the user saves an
empty field. The value can be literal or retrieved from the
message bundle with
a key such as |
||
|
optional Adds one or more style names to this component. Multiple styles can be
specified as a space-separated list of style names such as
|
||
|
optional Property transformer classes define how field values are stored in the repository. Each field has a default transformer class. You don’t need to define a class unless you want to override the default. The value is a fully-qualified class name.
|
||
|
optional, most fields set a default value automatically JCR property type of the stored value such as |
Field types
fieldType | class |
---|---|
text |
info.magnolia.ui.form.field.definition.TextFieldDefinition |
richText |
info.magnolia.ui.form.field.definition.RichTextFieldDefinition |
date |
info.magnolia.ui.form.field.definition.DateFieldDefinition |
hidden |
info.magnolia.ui.form.field.definition.HiddenFieldDefinition |
link |
info.magnolia.ui.form.field.definition.LinkFieldDefinition |
code |
info.magnolia.ui.form.field.definition.CodeFieldDefinition |
multiValue |
info.magnolia.ui.form.field.definition.MultiValueFieldDefinition |
password |
info.magnolia.ui.form.field.definition.PasswordFieldDefinition |
select |
info.magnolia.ui.form.field.definition.SelectFieldDefinition |
optionGroup |
info.magnolia.ui.form.field.definition.OptionGroupFieldDefinition |
twinColSelect |
info.magnolia.ui.form.field.definition.TwinColSelectFieldDefinition |
checkbox |
info.magnolia.ui.form.field.definition.CheckboxFieldDefinition |
composite |
info.magnolia.ui.form.field.definition.CompositeFieldDefinition |
switchable |
info.magnolia.ui.form.field.definition.SwitchableFieldDefinition |
static |
info.magnolia.ui.form.field.definition.StaticFieldDefinition |
basicUpload |
info.magnolia.ui.form.field.definition.BasicUploadFieldDefinition |
damUpload |
info.magnolia.dam.app.ui.field.definition.DamUploadFieldDefinition |
collapsibleComposite |
info.magnolia.editor.app.field.CollapsibleCompositeFieldDefinition |
expandingText |
info.magnolia.editor.app.field.ExpandingTextFieldDefinition |
Your Magnolia installation may contain more fields depending on the installed modules. Use the Definitions app to see all available field types.
Transformer classes
Default transformer classes:
-
For simple fields such as Text and Date:
info.magnolia.ui.form.field.transformer.basic.BasicTransformer
-
For composite fields:
info.magnolia.ui.form.field.transformer.composite.CompositeTransformer
-
For switchable fields:
info.magnolia.ui.form.field.transformer.composite.SwitchableTransformer
-
For multivalue fields:
info.magnolia.ui.form.field.transformer.multi.MultiValueTransformer
Other available transformer classes:
-
info.magnolia.ui.form.field.transformer.composite.DelegatingCompositeFieldTransformer
-
info.magnolia.ui.form.field.transformer.multi.DelegatingMultiValueFieldTransformer
-
info.magnolia.ui.form.field.transformer.composite.NoOpCompositeTransformer
-
info.magnolia.ui.form.field.transformer.multi.MultiValueJSONTransformer
-
info.magnolia.ui.form.field.transformer.multi.MultiValueChildrenNodeTransformer
-
info.magnolia.ui.form.field.transformer.multi.MultiValueChildNodeTransformer
-
info.magnolia.ui.form.field.transformer.multi.MultiValueSubChildrenNodeTransformer