Model Definitions, Fields, and Component Types
- Applies to:
- Experience Manager as a Cloud Service
- Topics:
- Developing
CREATED FOR:
- Admin
- Developer
Learn about fields and the component types that the Universal Editor can edit in the properties panel with examples. Understand how you can instrument your own app by creating a model definition and linking to the component.
Overview
When adapting your own apps for use with the Universal Editor, you must instrument the components and define what fields and component types they can manipulate in the properties panel of the editor. You do this by creating a model and linking to that from the component.
This document provides an overview of a model definition and of fields and the component types available to you along with example configurations.
TIPModel Definition Structure
In order to configure a component via the properties panel in the Universal Editor, a model definition has to exist and be linked to the component.
The model definition is a JSON structure, starting with an array of models.
[
{
"id": "model-id", // must be unique
"fields": [] // array of fields which shall be rendered in the properties panel
}
]
See the Fields section of this document for more information about how to define your fields array.
You can link a model to a component in two ways: using the component definition or via the instrumentation.
Linking Using the Component Definition
This is the preferred method of linking the model to the component. Doing so allows you to maintain the link centrally in the component definition and enables dragging components across containers.
Simply include the model property in the component object in the components array in the component-definition.json file.
For details, please see the document Component Definition.
Linking Using Instrumentation
To use the model definition with a component, the data-aue-model attribute can be used.
<div data-aue-resource="urn:datasource:/content/path" data-aue-type="component" data-aue-model="model-id">Click me</div>
- Projects that have implemented the link to the model via the instrumentation will continue to work as-is with no need for change.
- If you define the model in the component definition as well as in the instrumentation, the instrumentation will always be used.
Loading a Model Definition
Once a model is created, it can be referenced as an external file.
<script type="application/vnd.adobe.aue.model+json" src="<url-of-model-definition>"></script>
Alternatively you can also define the model inline.
<script type="application/vnd.adobe.aue.model+json">
{ ... model definition ... }
</script>
Fields
A field object has the following type definition.
componentComponentTypenamestringlabelFieldLabeldescriptionFieldDescriptionplaceholderstringvalueFieldValuevalueTypeValueTypestring, string[], number, date, booleanrequiredbooleanreadOnlybooleanhiddenbooleanmultibooleanvalidationValidationTyperawunknownComponent Types
The following are the component types that are possible to use for rendering fields.
aem-tagaem-contentbooleancheckbox-groupcontaineraem-content-fragmentdate-timeaem-experience-fragmentmultiselectnumberradio-groupreferencerichtextselecttabtextAEM Tag
An AEM tag component type enables an AEM tag picker, which can be used to attach tags to the component.
{
"id": "aem-tag-picker",
"fields": [
{
"component": "aem-tag",
"label": "AEM Tag Picker",
"name": "cq:tags",
"valueType": "string"
}
]
}
TIPAEM Content
An AEM content component type enables an AEM content picker, which can be used to select any AEM resource. Unlike the reference component, which can only select assets, the AEM content component can reference any AEM content. It offers an additional validation type.
rootPathstring{
"id": "aem-content-picker",
"fields": [
{
"component": "aem-content",
"name": "reference",
"value": "",
"label": "AEM Content Picker",
"valueType": "string",
"validation": {
"rootPath": "/content/refresh"
}
}
]
}
Boolean
A boolean component type stores a simple true/false value rendered as a toggle. It offers an additional validation type.
customErrorMsgstring{
"id": "boolean",
"fields": [
{
"component": "boolean",
"label": "Boolean",
"name": "boolean",
"valueType": "boolean"
}
]
}
{
"id": "another-boolean",
"fields": [
{
"component": "boolean",
"label": "Boolean",
"name": "boolean",
"valueType": "boolean",
"validation": {
"customErrorMsg": "Think, McFly. Think!"
}
}
]
}
Checkbox Group
Similar to a boolean, a checkbox group component type allows for the selection of multiple true/false items, rendered as multiple checkboxes.
{
"id": "checkbox-group",
"fields": [
{
"component": "checkbox-group",
"label": "Checkbox Group",
"name": "checkbox",
"valueType": "string[]",
"options": [
{ "name": "Option 1", "value": "option1" },
{ "name": "Option 2", "value": "option2" }
]
}
]
}
Container
A container component type allows the grouping of components. It offers an additional configuration.
collapsibleboolean {
"id": "container",
"fields": [
{
"component": "container",
"label": "Container",
"name": "container",
"valueType": "string",
"collapsible": true,
"fields": [
{
"component": "text-input",
"label": "Simple Text 1",
"name": "text",
"valueType": "string"
},
{
"component": "text-input",
"label": "Simple Text 2",
"name": "text2",
"valueType": "string"
}
]
}
]
}
Content Fragment
The Content Fragment picker can be used to select a Content Fragment and its variations (if required). It offers an additional configuration.
variationNamestringIt also offers an additional validation type.
rootPathstringNOTE[
{
"id": "aem-content-fragment",
"fields": [
{
"component": "aem-content-fragment",
"name": "picker",
"label": "Content Fragment Picker",
"valueType": "string",
"variationName": "contentFragmentVariation",
"validation": {
"rootPath": "/content/refresh"
}
}
]
}
]
Date Time
A date time component type allows the specification of a date, time, or combination thereof. It offers additional configurations.
displayFormatstringvalueFormatstringIt also offers an additional validation type.
customErrorMsgstringvalueFormat isn’t met{
"id": "date-time",
"fields": [
{
"component": "date-time",
"label": "Date & Time",
"name": "date",
"valueType": "date"
}
]
}
{
"id": "another-date-time",
"fields": [
{
"component": "date-time",
"valueType": "date-time",
"name": "field1",
"label": "Date Time",
"description": "This is a date time field that stores both date and time.",
"required": true,
"placeholder": "YYYY-MM-DD HH:mm:ss",
"displayFormat": null,
"valueFormat": null,
"validation": {
"customErrorMsg": "Marty! You have to come back with me!"
}
},
{
"component": "date-time",
"valueType": "date",
"name": "field2",
"label": "Another Date Time",
"description": "This is another date time field that only stores the date.",
"required": true,
"placeholder": "YYYY-MM-DD",
"displayFormat": null,
"valueFormat": null,
"validation": {
"customErrorMsg": "Back to the future!"
}
},
{
"component": "date-time",
"valueType": "time",
"name": "field3",
"label": "Yet Another Date Time",
"description": "This is another date time field that only stores the time.",
"required": true,
"placeholder": "HH:mm:ss",
"displayFormat": null,
"valueFormat": null,
"validation": {
"customErrorMsg": "Great Scott!"
}
}
]
}
Experience Fragment
The Experience Fragment picker can be used to select an Experience Fragment and its variations (if required). It offers an additional configuration.
variationNamestringIt also offers an additional validation type.
rootPathstring[
{
"id": "experience-fragment",
"fields": [
{
"component": "aem-experience-fragment",
"valueType": "string",
"name": "experience-fragment",
"label": "experience-fragment",
"variationName": "experienceFragmentVariation",
"validation": {
"rootPath": "/content/refresh"
}
}
]
}
]
Multiselect
A multiselect component type presents multiple items for selection in a drop-down including the ability to group the selectable elements.
{
"id": "multiselect",
"fields": [
{
"component": "multiselect",
"name": "multiselect",
"label": "Multi Select",
"valueType": "string",
"options": [
{ "name": "Option 1", "value": "option1" },
{ "name": "Option 2", "value": "option2" }
]
}
]
}
{
"id": "multiselect-grouped",
"fields": [
{
"component": "multiselect",
"name": "property",
"label": "Multiselect field",
"valueType": "string",
"required": true,
"maxSize": 2,
"options": [
{
"name": "Theme",
"children": [
{ "name": "Light", "value": "light" },
{ "name": "Dark", "value": "dark" }
]
},
{
"name": "Type",
"children": [
{ "name": "Alpha", "value": "alpha" },
{ "name": "Beta", "value": "beta" },
{ "name": "Gamma", "value": "gamma" }
]
}
]
}
]
}
Number
A number component type allows for the input of a number. It offers additional validation types.
numberMinnumbernumberMaxnumbercustomErrorMsgstringnumberMin or numberMax isn’t met{
"id": "number",
"fields": [
{
"component": "number",
"name": "number",
"label": "Number",
"valueType": "number",
"value": 0
}
]
}
{
"id": "another-number",
"fields": [
{
"component": "number",
"valueType": "number",
"name": "field1",
"label": "Number Field",
"description": "This is a number field.",
"required": true,
"placeholder": null,
"validation": {
"numberMin": 0,
"numberMax": 88,
"customErrorMsg": "You also need 1.21 gigawatts."
}
}
]
}
Radio Group
A radio group component type allows for a mutually-exclusive selection from multiple options rendered as a group similar to a checkbox group.
{
"id": "radio-group",
"fields": [
{
"component": "radio-group",
"label": "Radio Group",
"name": "radio",
"valueType": "string",
"options": [
{ "name": "Option 1", "value": "option1" },
{ "name": "Option 2", "value": "option2" }
]
}
]
}
Reference
An reference component type enables an AEM asset picker, which can be used to select any AEM asset to reference. Unlike the AEM content component, which can select any AEM resource, the reference component can only reference assets. It offers an additional validation type.
A reference component type allows for a reference to another data object from the current object.
{
"id": "reference",
"fields": [
{
"component": "reference",
"label": "Reference",
"name": "reference",
"valueType": "string"
}
]
}
Rich Text
Rich text allows for multi-line, rich text input.
{
"id": "richtext",
"fields": [
{
"component": "richtext",
"name": "rte",
"label": "Rich Text",
"valueType": "string"
}
]
}
Select
A select component type allows for selection of a single option from a list of predefined options in a drop-down menu.
{
"id": "select",
"fields": [
{
"component": "select",
"label": "Select",
"name": "select",
"valueType": "string",
"options": [
{ "name": "Option 1", "value": "option1" },
{ "name": "Option 2", "value": "option2" }
]
}
]
}
Tab
A tab component type allows you to group other input fields together on multiple tabs to improve layout organization for the authors.
A tab definition can be thought of as a separator in the array of fields. Everything that comes after a tab will be placed on that tab until a new tab is encountered, whereafter the following items will be placed on the new tab.
If you wish to have items that appear above all tabs, they must be defined before any tabs.
{
"id": "tab",
"fields": [
{
"component": "tab",
"label": "Tab 1",
"name": "tab1"
},
{
"component": "text-input",
"label": "Text 1",
"name": "text1",
"valueType": "string"
},
{
"component": "tab",
"label": "Tab 2",
"name": "tab2"
},
{
"component": "text-input",
"label": "Text 2",
"name": "text2",
"valueType": "string"
}
]
}
Text
Text allows for a single line of text input. It includes additional validation types.
minLengthnumbermaxLengthnumberregExpstringcustomErrorMsgstringminLength, maxLength, and/or regExp is/are violated{
"id": "simpletext",
"fields": [
{
"component": "text",
"name": "text",
"label": "Simple Text",
"valueType": "string"
}
]
}
{
"id": "another simpletext",
"fields": [
{
"component": "text",
"name": "text",
"label": "Simple Text",
"valueType": "string",
"valueFormat": "regexp",
"description": "This is a text input with validation.",
"required": true,
"validation": {
"minLength": 1955,
"maxLength": 1985,
"regExp": "^foo:.*",
"customErrorMsg": "Why don't you make like a tree and get outta here?"
}
}
]
}
