Experience Manager provides a set of standard editors that you can use in cartridge templates as well as the ability to develop custom editors.
You can provide embedded assistance for the business user in the Experience Manager interface by specifying it in the cartridge template.
In our example cartridge, we provided two simple text fields for the
business user to enter a message and the desired color. This user interface
makes it unclear what values are allowed or expected for those fields. The
template schema for configuring editors allows you to supply a short
descriptive label for each field, but sometimes additional context can be
helpful. For such cases, you can use the
bottomLabel
attribute to provide further information.
To add additional guidance for the business user to the example cartridge:
Open the template file (
HelloWorld\_.json
) that you previously created.Add a
bottomLabel
attribute to each editor in theEditorPanel
, as in the example below:"editorPanel": { "editor": "editors/DefaultEditorPanel", "children": [ { "editor": "GroupLabel", "label": "${group.contents.label}" }, { "editor": "editors/StringEditor", "propertyName": "message", "label": "Message", "bottomLabel": "Enter a message to display. HTML is allowed." }, { "editor": "editors/StringEditor", "propertyName": "messageColor", "label": "Color" } ] },
This additional label text can be configured for all editors built using the Experience Manager SDK, including all the standard editors. For the full content of the updated template, see the example below. If your implementation uses multiple locales, see About multiple locales for information about localizing strings.
The following shows the complete content of the updated template:
{ "ecr:type": "template", "@group": "SecondaryContent", "@description": "A sample cartridge that can display a simple message", "@thumbnailUrl": "thumbnail.jpg", "defaultContentItem": { "@name": "Hello cartridge", "message": "", "messageColor": "" }, "editorPanel": { "editor": "editors/DefaultEditorPanel", "children": [ { "editor": "GroupLabel", "label": "${group.contents.label}" }, { "editor": "editors/StringEditor", "propertyName": "message", "label": "Message", "bottomLabel": "Enter a message to display. HTML is allowed." }, { "editor": "editors/StringEditor", "propertyName": "messageColor", "label": "Color" } ] }, "typeInfo": { "message": {"@propertyType": "String"}, "messageColor": {"@propertyType": "String"} } }
For more information about label options for Experience Manager editors, see the Editor label configuration reference.
Experience Manager provides a set of editors that can configure
primitive property types as well as Oracle Commerce-specific features. You
specify which editor to use to configure which properties in the
<EditorPanel>
portion of the template.
Even with additional user assistance text, asking the business user to type a hex code into a text field does not provide a very user-friendly experience. One of the standard editors included with Experience Manager is a combo box that can be used to specify a set of valid values for a string property. In this example, we provide a set of colors from which the business user can choose. This not only relieves the business user from typing in a hex code, but it can also ensure that the selected color matches the site's color scheme.
To update the example cartridge to use a combo box editor:
Open the template file,
HelloWorld\_.json
, that you previously created.Replace the string editor configuration for the
messageColor
property with the following:"editorPanel": { "editor": "editors/DefaultEditorPanel", "children": [ { "editor": "GroupLabel", "label": "${group.contents.label}" }, { "editor": "editors/StringEditor", "propertyName": "message", "label": "Message", "bottomLabel": "Enter a message to display. HTML is allowed." }, { "editor": "editors/ChoiceEditor", "label": "Color", "propertyName": "messageColor", "choices": [ { "label": "Red", "value": "#FF0000" }, { "label": "Green", "value": "#00FF00" }, { "label": "Blue", "value": "#0000FF" } ] } ] }
For the full content of the updated template, see the example below.
Depending on the option that the business user selects, the value of the property is set to the appropriate hex code. You can change the value and refresh the application to see the change.
The following shows the complete content of the updated template:
{ "ecr:type": "template", "@group": "SecondaryContent", "@description": "A sample cartridge that can display a simple message", "@thumbnailUrl": "thumbnail.jpg", "defaultContentItem": { "@name": "Hello cartridge", "message": "", "messageColor": "" }, "editorPanel": { "editor": "editors/DefaultEditorPanel", "children": [ { "editor": "GroupLabel", "label": "${group.contents.label}" }, { "editor": "editors/StringEditor", "propertyName": "message", "label": "Message", "bottomLabel": "Enter a message to display. HTML is allowed." }, { "editor": "editors/ChoiceEditor", "label": "Color", "propertyName": "messageColor", "choices": [ { "label": "Red", "value": "#FF0000" }, { "label": "Green", "value": "#00FF00" }, { "label": "Blue", "value": "#0000FF" } ] } ] }, "typeInfo": { "message": {"@propertyType": "String"}, "messageColor": {"@propertyType": "String"} } }
For more information about the standard Experience Manager editors and their configuration, refer to the Template Property and Editor Reference.
If none of the standard editors meet your needs, you can develop your own editors using the Experience Manager Editor SDK.
You may want to develop an editor if:
You want to allow the business user to configure more advanced properties such as lists or maps of key-value pairs.
You want to provide a more advanced interface for the business user, such as a list that enables drag-and-drop.
You want the editor options to be populated dynamically from an external system rather than configured in the template.
You want the behavior of one editor or UI control to be linked to the state of another.
For more information about the Experience Manager Editor SDK and developing Experience Manager editors, see Developing Custom Editors.