Oxygen XML Web Author supports form controls to allow the inline editing of XML attributes or XML elements with a specific structure. Along with the built-in form controls (such as buttons, text fields, combo boxes, etc.), Web Author also provides support for custom form controls. Some of the possible use cases include:
- Editing XML fragments with a specialized structure (for example, MathML equations)
- Editing attributes whose possible values are given by an external service (for example, book reference numbers)
- Editing external meta-information associated with an XML element (for example, comments stored in the CMS)
A custom form control can be associated with an element using the custom CSS function oxy_editor. They need to have a
webappRendererClassName property that specifies the Java class that handles the initial rendering of the form-control.
The class needs to extend the ro.sync.ecss.extensions.api.webapp.formcontrols.WebappFormControlRenderer and to
create an HTML fragment to be included in the rendered version of the document.
A custom form control can also have some client-side code to define its behavior. This code should provide an
implementation of the sync.formctrls.Enhancer base class. To modify the document, an Enhancer may use
the actions manager to invoke server-side operations. The following is an example that inserts an empty element at the cursor position:
editor.getActionsManager().invokeOperation('ro.sync.ecss.extensions.commons.operations.InsertOrReplaceFragmentOperation', {
fragment: '<element/>',
insertLocation: ".",
insertPosition: "Replace"
}, callback);
The way that an enhancer is registered differs if it is part of a framework or a plugin. Both cases are discussed below.
Registering a Custom Form Control from a Framework
If using a framework, this code should register an sync.ext.Extension object using the
sync.ext.Registry.registerExtension function. The script may use sync.ext.Registry#getExtensionURL to
find a URL that maps to the web/ folder of the framework.
Then, the sync.ext.Extension#getEnhancers method should be used to provide a mapping from the Java-based renderer (fully-qualified) class name to the constructor functions of the enhancers.
Registering a custom Form Control from a Plugin
In a plugin, form control enhancers can be registered using sync.api.Editor#registerEnhancer.
Example
An example implementation can be found on GitHub in the web-author-mathml-plugin project.