The Editor SDK provides Editor, an abstract base JavaScript extension. The Editor extension defines the life cycle for executing a custom editor.
Custom editors extend the base Editor class.
The
Editor(pConfig) constructor is invoked when a
cartridge template corresponding to an asset is loaded into Experience Manager.
The framework instantiates every editor in the order that they are mapped in
the template's editor panel. The framework passes the configuration object that
is built from various configurations defined at the cartridge template and
editor levels to the editor's constructor.
The
Editor(pConfig) constructor instantiates all the
editor-level properties and helper objects.
pConfig is the editor's configuration that is supplied in a
specific EAC application context. This is the configuration that you define in
the editor's _.json file using
config attribute.
This section describes the following life cycle methods. Note that override is optional for all of them.
The framework invokes the initialize life cycle method immediately after the instantiation of the editor that passes the template configuration object and content item.
Parses meta information configured in the cartridge template and populates the same into the editor object. This meta information can be specific to:
Label. For example, localized label name, label position, localized tool-tip information and so on.
Generic validations. For example, whether or not the property is required, or the editor is enabled.
Validation meta information specific to editor. For example, the NumericStepperEditor might have a number range validator that can be turned on based on minimum or maximum values.
Additional information specific to the editor. For example, the ChoiceEditor has a list of choices to be displayed.
Subscribes to notifications that are pertinent to the editor.
Initializes custom controllers if there are any specific to editor.
The initialize method in the base Editor parses
TemplateConfigand populates attributes like localized label text, tool tips, orenabledExpressionthat are common for all Experience Manager editors.If a custom editor needs any additional meta information specific to that editor, it must override the initialize method and populate the same.
If overridden, this method must explicitly call its initialize method from its super class Editor.
Editor.prototype.initialize.call(this, pTemplateConfig, pContentItem)
|
Parameter |
Description |
|---|---|
|
pTemplateConfig |
Object that holds the cartridge template-level configuration associated with the editor. |
|
pContentItem |
For more information on the property API, see Property API. |
When initialization is finished, the framework binds editors to the
view and moves them to Loading phase. The actual data binding occurs in the
editorReady method.
Once initialization is successful, the framework invokes the
editorReady life cycle method and passes the
appropriate property instance created by the framework.
An editor can override this method, if it needs to wrap the property
using any custom extension to the property API or any computations regarding
the property value. If overridden, this method must explicitly call
editorReady from it's super class Editor:
Editor.prototype.editorReady.call (this, pProperty)
|
Parameter |
Description |
|---|---|
|
pProperty |
Property object from the content item which is mapped to this editor in the cartridge template's editor panel. An editor can work with multiple properties, but at any
given time, only one property can be mapped against attribute
Based on the property's value type, the framework wraps the property in the appropriate class provided by the framework. |
For more information on the property API, see Property API.
In the
editorReady method of an editor, you can load any data
needed by an editor asynchronously. For example, DimensionListEditor needs to
load dimension names from MDEX. You should ensure that the
editorReady method in the super class is called only
when all asynchronous calls have completed. This allows the framework to call
editorReady on individual editors asynchronously. When
an editor is ready, the framework removes the Loading phase and renders the
user interface using the editor's own HTML template.
The framework invokes the
editorError life cycle method when there are errors
during the
initialize() and
editorReady () life cycle phases. This method can also
be explicitly invoked to handle error scenarios.
There is no need for an editor to override
editorError until a different error template must be
bound to the editor in error scenarios.
The framework invokes this method before de-referencing (marking) this editor instance for garbage collection.
The framework invokes this method internally by Oracle JET when a workbench user re-visits a previously visited mini-tree node. The method is invoked on each editor instance mapped to that particular node content.
When a page or rule is edited, and after loaded editor instances are cached (when a Workbench user clicks a specific mini-tree node for the first time), all the editors that are mapped to the node's content are instantiated and cached. From this point forward, whenever a Workbench user attempts to revisit the same node, editors are loaded from cache. This action happens because any form errors or modifications to a rule's or page's properties should be retained, even when a user navigates through the mini-tree's nodes.
This is a hook method to perform any post activities once an editor has been reloaded from cache. For example, you might want to re-subscribe for any topics at the editor level. In such a scenario, a specific editor can override this method and implement the appropriate post processing logic.
Note: This will not be called when editor is instantiated and loaded for the first time.
The framework invokes this method internally by Oracle JET when a workbench user exits or switches from the current mini-tree node. The method is invoked on each editor instance mapped to that particular node content.
When a page or rule is edited, and after loaded editor instances are cached (when a Workbench user clicks a specific mini-tree node for the first time), all the editors that are mapped to the node's content are instantiated and cached. From this point forward, whenever a workbench user attempts to revisit the same node editors are loaded from cache. This action happens because any form errors or modifications to a rule's or page's properties should be retained, even when a user navigates through the mini-tree's nodes. However, there might be some events that can trigger changes in a rule's or page's property even when not in view.
This is a hook method to perform any post activities, once an editor has been removed from the document DOM. For example, you might want to unsubscribe any topics at the editor level. In such a scenario, a specific editor can override this method and implement the appropriate logic.
This JavaScript-based property API is used for the following functions:
Wrapping property raw data (this how a property is stored in the ECR) in a property instance which is easily consumed by an editor's Knockout view model and html template.
When editing is complete, converting property instance back into a format in which it has to be stored into the ECR.
Notifying other JavaScript components about changes to property values. This can be used in reevaluating enable expressions when a dependent property value changes, for example, enabling/disabling user interface controls and so on.
|
Class |
Description |
Methods |
|---|---|---|
|
Property |
The core property class that wraps the property's raw JSON data. It also defines custom Knockout subscriptions to track changes made to a property value. Whenever there is a change in a property value, a EditorEvents.PROPERTY_CHANGED event is triggered.. The property reference that was modified is passed as the event payload. Every editor has an observable property that is set to the property reference that editor works with. |
copyFrom (pProperty) - Accepts raw the JSON object that represents a valid property with a name, type, and an optional value. Used to update any bindings that are needed by the user interface. Basic functionality is to set value as a Knockout observable or observableArray. toJSON() - Converts the property instance to JSON, in a format to be stored in the ECR. For example, a property instance will have observable or observableArray to bind value to the editor, which has to be converted to normal value. |
|
StringProperty |
A subclass of Property class. Deals with property objects. Value type is a String. | |
|
BooleanProperty |
A subclass to Property class. Deals with property objects. Value type is a Boolean. |
Overrides the copyFrom method, and wraps property's value in a Boolean. |
|
JSONProperty |
A subclass to Property for Item and List types. This is used to wrap properties whose values are either JSONObject or JSONArray. When the framework parses a content item, in case of a list, it would not be possible to distinguish whether the value is a primitive list or an object list. Also in case of Item, it is not possible to determine value is of which object type. In these scenarios, the framework wraps a property in JSONProperty and passes it to the editorReady method of the corresponding editor. Within the editorReady method, the corresponding property instance (ObjectProperty, ListProperty, ObjectListProperty, or any extension to Property that customers might develop and plug in) can be created as an editor will know about the value type that it is working with. This is also used when there is no type specified for a property. |
Overrides copyFrom method and sets property's value as an observable or observableArray based on the type. Overrides toJSON method and converts the property instance to JSON, in a format to be stored in ECR. |
|
ObjectProperty |
A subclass to Property class for property objects whose value is an object. This is needed to manipulate internal attributes of the object. Otherwise JSONProperty works with Object. For example in case of media property in MediaBanner cartridge, whose value is an object, there are attributes which are computed based on some other attributes in the object. "media": {
"@class": "com.endeca.infront.
cartridge.model.MediaObject",
"uri": "banner_bags_761x225.jpg",
"contentWidth": "761",
"contentHeight": "225",
"contentBytes": "3546313",
"contentType": "Image",
"contentSrcKey": "default"
}In this object, based on the image that we select, for example the uri attribute, other attributes like contentWidth, contentHeight, contentBytes, contentType are computed. We can define a Image.js model object that uses a Knockout computed observables concept to compute these attributes based on the uri attribute. This Image must be wrapped using ObjectProperty. |
Overrides the following methods: copyFrom: Copies property's value into corresponding ObjectValue instance. toJSON: Converts the property's value into JSON format, in a format to be stored in ECR. |
|
ObjectListProperty |
A subclass to Property for property objects whose value is an array or a list built from objects. As described for ObjectProperty, this is needed only when performing custom manipulations on an object's attributes. Otherwise use JSONProperty. |
Overrides the following methods: copyFrom: Copies each object in the list into corresponding ObjectValue instance. toJSON: Converts each object in the value list into JSON format, in a format to be stored in ECR. |
|
ContentItemProperty |
A subclass to ObjectProperty for property objects whose value is an object of type ContentItem. | |
|
ContentItemListProperty |
A subclass to ObjectListProperty for property objects whose value is an array or a list built from objects, of type ContentItem. This also stores data in a tree structure. | |
|
ObjectValue |
A wrapper to property value which is an object. Provides method signatures to be implemented by any object values. |
copyFrom(pPropertyValue): Copies plain JSON object into the ObjectValue. For example, in SortOption, there can be an observable label, which would be populated under the copyFrom(..) method. toJSON(): In Experience Manager, the implementation converts the Knockout object back to a plain JSON object. |
