Integrating Web Author in a CMS or Another Application

Oxygen XML Web Author can be embedded in a CMS to offer editing functionality for documents stored in the CMS. It can also be embedded in other web applications.

Web Author has two parts that need to be considered when integrating:
  1. A front-end HTML page that should be embedded using an iframe (load the main page (app/oxygen.html) in an iframe). Some of its options can be controlled using URL parameters and others by using the Oxygen XML Web Author JavaScript API from a plugin.
  2. The Java-based back-end that can also be customized using plugins.
    Note: It is recommended to deploy the back-end separately from your application. More details here: Sharing a Tomcat Instance.

Security Restrictions

Oxygen XML Web Author uses cookies to enforce its licensing and to maintain the editing state of the opened documents. Some browsers block third-party cookies for security reasons. To avoid having the cookies blocked, Oxygen XML Web Author should be served from the same origin as the CMS host page.

Passing URL Parameters to the Editor

To control the editor, you can use URL parameters.

The allowed URL parameters are as follows:
  • url - The OXY-URL that identifies the file to be opened.
  • ditamap - (Optional parameter for DITA files) The OXY-URL of the DITA Map to use as a context for resolving keys.
  • author - The author name.
  • trackChanges - Flag that controls whether or not the editor should track changes. The possible values are:
    • default - The status of change tracking is determined by the server's global options.
    • enabled - Change tracking is enabled but the user can disable it using a toolbar action.
    • forced - Change tracking is enabled and the user cannot disable it. The user can reject their own changes, but cannot accept or reject changes made by others.
    If you use an option other than default, the server change tracking status (as configured in the Administration Page) should not be "Stored in the document". For more information about this parameter, see Control Change Tracking State
  • autoSaveInterval - The interval of time (in seconds) to wait until an auto-save is performed. If <= 0 or false, auto-save is disabled.
  • expandTopicRefs - If set to true, when a DITA map is opened in Oxygen XML Web Author, the content of all topics referenced in the map will be presented.
  • lang - You can use this parameter to impose a specific language for the Oxygen XML Web Author interface. The possible values are:
    • en_US - English
    • de_DE - German
    • fr_FR - French
    • ja_JP - Japanese
    • nl_NL - Dutch
  • ccOnEnter - If set to true, the content completion popup window is displayed when the user presses Enter. If set to false, the Enter key works similar to the behavior in normal word processors.

To pass custom parameters, you can implement a plugin for Oxygen XML Web Author that contains JavaScript code to interpret those parameters and configure the editor (sync.api.Workspace.LoadingOptions).

Communicating with the Editor

To communicate with the editor, you can send messages between the host CMS page and the Oxygen XML Web Author page.

Browsers offer the window.postMessage JavaScript API that allows messages to be sent between pages. To receive the message, create a plugin for Oxygen XML Web Author that contains JavaScript code that listens for the messages sent by the CMS host page and uses the Oxygen XML Web Author JavaScript API to implement the required functionality.

Other Notes

  • We experienced problems if the iframe is hidden while loading using display: none. You can use visibility: hidden for the same purpose.
  • Some XML vocabularies (for example, DITA) support cross-document links. By default, clicking on a cross-document link will open that document in the Oxygen XML Web Author in another browser tab. If the editor is embedded, you may want to change this behavior using the sync.api.Editor.EventTypes.LINK_OPENED event that is triggered on the sync.api.Editor instance.
  • When embedded in a larger page, sometimes it makes sense to remove the gray app-bar that contains the application logo, file name, and user name. To do this, you can use the workspace.getViewManager().hideAppBar(); API.
  • It is possible to customize the Oxygen XML Web Author user interface through the use of JavaScript APIs. For more information, see Customizing Web Author User Interface.