Edit online

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 open 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:
General Parameters
  • url - The OXY-URL that identifies the file to be opened.
  • folderUrl - You can use this parameter to navigate to the Dashboard with the corresponding repository tab open and the content of the specified folder displayed.
  • userName - The user name of the author.
  • autoSaveInterval - The interval of time (in seconds) to wait until an auto-save is performed. If set to 0, the auto-save is disabled.
  • 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 a normal word processor application.
  • hideBreadcrumb - If set to true, the breadcrumb will not be displayed in the interface.
  • 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
    • zh_CN - Chinese
  • spell.check.language - Specifies the default language used for spell checking in the document. The value must be in either a 2-digit or 4-digit language code format (for example, en or en_US).
  • 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.
      Note: If you use a value 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 the State of Change Tracking.

  • contentType - For cases where Web Author cannot open a document that has an unrecognized file extension, you can use this parameter as a loading option to pass a specific file type so that client-side editing support can be used for editing the document. You can also specify an encoding type. Examples for values:
    • image/png
    • application/xml
    • text/markdown;charset=utf-8
  • textModeReadOnly - If set to true, the Web Author XML text editing mode will always be set to read-only.
  • tags-mode - You can use this parameter to specify the Tags Display Mode for the document. The possible values are:
    • full-tags-with-attributes - Displays full tag names with attributes for both block and inline elements.
    • full-tags - Displays full tag names without attributes for both block and inline elements.
    • block-tags - Displays full tag names for block elements and simple tags without names for inline elements.
    • inline-tags - Displays full tag names for inline elements, while block elements are not displayed.
    • partial-tags - Displays simple tags without names for inline elements, while block elements are not displayed.
    • no-tags - No tags are displayed.
  • compactTagsMode - If the user has the Tags Display Mode option set to any value that shows the XML tags, setting this parameter to true will compact the tags (for example, multiple tags presented on the same line). If set to false, each tag of a block element is presented on a separate line.
  • quickUpDownNavigation - If set to true, horizontal cursor positions between block elements are avoided. It also forces tags of block elements to be displayed on separate lines, if visible.
  • diffUrl (File Comparison Tool parameter) - This parameter can be used in conjunction with the url parameter to specify files to compare with each other. This parameter specifies the URL of the file to be opened in the right side of the file comparison tool while the url parameter specifies the URL of the file to be opened in the left side.
  • diffBaseUrl (File Comparison Tool parameter) - This parameter can be used in conjunction with the url and diffUrl parameters to perform a 3-way file comparison. This parameter specifies the URL of the original base file, while the url parameter specifies the URL of the file to be opened in the left side of the file comparison tool (the local file), and the diffUrl parameter specifies the URL of the file to be opened in the right side (the remote file).
  • diffType (File Comparison Tool parameter) - Use merge for the value to allow merging. This opens the comparison in the Merge tool. If this parameter is not specified, the normal File Comparison tool is opened and the left editor is not editable.
  • leftEditorLabel (File Comparison Tool parameter) - This parameter can be used to specify the label used for the name of the file in the left side of the file comparison tool. Normally, the file name is used.
  • rightEditorLabel (File Comparison Tool parameter) - This parameter can be used to specify the label used for the name of the file in the right side of the file comparison tool. Normally, the file name is used.
  • runDiffOnChange (File Merge Tool parameter) - This parameter can be used to control whether or not the visual highlights are updated automatically when the user makes changes to the document in the Web Author Merge tool. Possible values are: true, false, and auto (default value and it means that the value is set as true if the size of the merged file is less than 10 KB, otherwise it is set to false). It is useful to set this parameter to false for large documents.
  • schematron.imposed.phase - This parameter can be used to impose the Schematron phase to use when validating with a Schematron file.
  • schematronUrl (Markdown-specific parameter) - This parameter can be used to specify the URL of a Schematron file that will be used to validate the Markdown document.
  • searchMode - This parameter can be used to specify whether the search action opens the Find/Replace mechanism as a pop-up window or as a side view. The possible values are: dialog (default) or sideView.
  • outlinePlacement - Specifies the side of the interface where the Outline pane is placed. Accepted values are: left or right.
  • image-cache-size - Specifies the size (in bytes) of the in-memory image cache that Oxygen XML Web Author uses inside the web browser. By default, the cache size is 10000000 bytes. If you encounter images loading slowly (particularly when the same images are loaded multiple times), you can increase the cache size limit to improve performance.
DITA-specific Parameters
  • ditamap - The OXY-URL of the DITA Map to use as a context for resolving keys.
  • ditaMapSide - Used to control whether the DITA Map pane is displayed on the left or right side of the editor. Possible values are left or right.
  • dita.project.url - Specifies the URL of the DITA project file.
  • dita.project.contextid - Can be used in conjunction with the dita.project.url parameter to specify the context declared inside the DITA project file.
  • dita.val.url - The OXY-URL of a DITAVAL filter. It is used for resolving keys whose values depend on profiling conditions and it grays out content that is excluded by the DITAVAL filter.
  • show.excluded.content - If set to true, when a DITAVAL filter is used, the content excluded by the DITAVAL filter will be shown as being grayed out. If set to false, the excluded content is hidden.
    Note: This parameter has no effect inside the file comparison tool.
  • KeyscopeStack - Used for resolving keys when DITA 1.3 key scopes are defined in the DITA map. The value looks like this:
    a b c,d e f
    for a DITA map that has the key scope defined like this:
    <topicref keyscope="a b c"><topicref keyscope="d e f"/></topicref>
  • 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.
  • diffDitamap (File Comparison Tool parameter) - This parameter can be used to specify a DITA map for the right-side editor.
  • diff.dita.val.url (File Comparison Tool parameter) - This parameter can be used to specify the URL of a DITAVAL file for the right-side editor.
  • showDitaMapView - When set to true, the DITA Map view will automatically be displayed.
  • showTopicTitles - When set to true, topic titles are resolved and displayed when a DITA map is opened (the same as if the View Topic Titles mode is selected in the DITA map display mode drop-down).
  • inplaceReferenceEditingSupported - Can be set to true if the CMS connector is prepared to save user changes in files referenced from the open document. When this option is enabled, the Edit Topic Content mode becomes available when opening a DITA Map.

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.

Redirecting Problem Reports

Users can report problems they experience using Oxygen XML Web Author by using the Report problem action in the More drop-down menu located in the top toolbar. By default, the reports are sent to an HTTP endpoint on http://oxygenxml.com. When Oxygen XML Web Author is embedded in another application (such as a CMS), the reports should be redirected to an HTTP endpoint managed by the CMS.

To override the default and redirect the problem reports, you can set the value of the com.oxygenxml.report.problems.url system property on the Web Author server to the URL where the report should be sent.

Other Notes

  • 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 the Web Author User Interface.
  • It is possible to experience problems if the iframe is hidden while loading using display: none. You can use visibility: hidden for the same purpose.