Edit online

Web Author API Concepts

Oxygen XML Web Author is a web application with two components:

  • The back-end is implemented in Java. It stores the DOM model of the document and is responsible for advanced processing of the XML document (such as validation and executing operations whose behavior is influenced by the document schema).
  • The front-end is implemented in JavaScript. It renders the user interface of the editor, provides basic access to the document model, and makes requests to the back-end to modify the document in response to user actions. Some performance-sensitive actions (such as typing) are first executed on the front-end and then the result is synchronized with the back-end.

Each of the components offers an API that can be used from a framework or plugin.

JavaScript API Concepts

Workspace
The workspace global variable is the entry point for the JavaScript API. It provides access to functions and objects for that particular browser tab (or iframe in case of an integration). The workspace has side-views that can be configured.
Editor
In a workspace, one or more editors are loaded. The editor represents the area where the document to be edited is rendered.
Editing Support
When an Editor is loaded, depending on the type of document, an editing support is created. It can be one of the following:
  • Author mode editing support - Used for XML documents to provide WYSIWYG editing features.
  • Markdown editing support - Used to edit Markdown documents.
  • Plain-text editing support - Used to provide read-only access to text documents.
  • Image editing support - Used to provide view-only access to images.
  • Diff editing support - Used by the File Comparison plugin to display two documents side-by-side.
  • Custom editing supports - Can be implemented for other use-cases.

If a document fails to load, no editing support is created.

Loading Option
Configuration options that can be specified before the editor loading is attempted, for example:
goog.events.listen(workspace, sync.api.Workspace.EventType.BEFORE_EDITOR_LOADED,
  function(e) {
    if (e.options.url.endsWith('.dita')) {
      // DITA files will be opened in no-tags mode.
      e.options['tags-mode'] = 'no-tags';
    }
});

For a list of available options, see the JavaScript API documentation.

Action
An action is a JavaScript object that extends the sync.actions.AbstractAction class that implements a behavior and is configured with rendering information such as icons or text descriptions. Some actions are automatically constructed from the framework configuration and others are explicitly implemented in JavaScript extensions. Such an action can be added to the toolbar, contextual menu, or Content Completion Assistant.
Operation
An operation is a Java implementation of the ro.sync.ecss.extensions.api.AuthorOperation interface. It can be invoked asynchronously from the JavaScript code using sync.api.ActionsManager#invokeOperation. This is the primary way to communicate between JavaScript API and Java API.
Enhancer
An Enhancer is a JavaScript class used to make a custom form-control rendered on the back-end interactive.

Java API Concepts

PluginWorkspace
An object instance of ro.sync.ecss.extensions.api.webapp.access.WebappPluginWorkspace that can be used to make global customizations that affect all users (such as registering a URIResolver).
Editing Session
Corresponds to an XML document opened in a browser tab. It is the back-end counterpart of an Author mode editing support.
System ID
The OXY-URL of a the current document.
Context ID
A token that uniquely identifies a user session connected to the Oxygen XML Web Author back-end. It is stored in the userInfo part of the System ID and is the same for all documents opened in the same user session.
User Session
The session established between the user's browser and the Oxygen XML Web Author back-end using a session cookie.
AuthorDocumentModel
An instance of the ro.sync.ecss.extensions.api.webapp.AuthorDocumentModel, the server-side model of the current XML document.
Operation
An operation is a Java implementation of the ro.sync.ecss.extensions.api.AuthorOperation interface. An operation makes an atomic edit of the document. Some operations may extend ro.sync.ecss.extensions.api.webapp.AuthorOperationWithResult to return a result when invoked by JavaScript code.
Framework
A set of files that configure the editor for a particular XML vocabulary. The main file of a framework is the framework descriptor and has a .framework file extension. This descriptor has references to additional configuration files.
Form Control
An embedded widget that can be used to provide specialized editing interfaces for XML attributes and elements. Some examples are combo-boxes, radio buttons, or date pickers.
Styles
Oxygen XML Web Author uses CSS to render a document. After matching CSS rules against an element, a set of styles are determined for rendering the element .
Pseudo-element
Boxes whose rendering can be configured using CSS, but do not appear in the XML document. For example:
note:before {
  content: "Note:";
}
Pseudo-class
A flag that can be set on an XML node while the document is opened in the editor. They are not serialized in the XML document but can be used in CSS selectors. For example:
colspecs:closed > * {
  display: none;
}
Schema-Aware
A mode of operation where schema information is taken into account by editing functions (for example, when the user tries to insert an element in an invalid position, the editor inserts the element in a nearby position where it is valid).