Edit online

Customizing the Web Author User Interface

It is possible to customize the Oxygen XML Web Author user interface (including the side views, toolbars, contextual menu actions, and theme).

Customizing the Toolbar and Contextual Menu Actions

The Oxygen XML Web Author toolbar and contextual menu structure includes standard actions (such as Undo, Redo, Cut, etc.) as well as actions that are dictated by the framework configuration.

There are several methods you can use to customize the actions that appear on the toolbar and contextual menu:
Document Type Configuration in Oxygen XML Editor/Author
You can use the Document Type configuration dialog box in Oxygen XML Editor/Author (Options > Preferences > Document Type Association > [select framework] > Edit). This approach is entirely GUI-based and controls only the framework-specific configuration. You can add and remove actions, create drop-down sub-menus, or add separators.
Note: If the framework contains Author mode operations (Java implementations of the ro.sync.ecss.extensions.api.AuthorOperation interface), they can be enabled to be used by Oxygen XML Web Author using the ro.sync.ecss.extensions.api.WebappCompatible annotation. Author mode operations that use Java Swing components to display a graphical interface are not compatible with the Oxygen XML Web Author and they should not be annotated. If you want to prompt the user for input, you can use the ${ask} editor variable or use the JavaScript API.
Web Author JavaScript API

You can use the Web Author JavaScript API to add custom actions or remove actions from the toolbar and contextual menu.

The advantages of using this approach include:
  • You can remove any action, even standard ones.
  • You can remove actions from all the places where they appear in the GUI.
  • You can dynamically remove actions (for example, based on the user role).
  • You can add actions that have a web-based GUI.
The base configuration of the toolbar and contextual menu for built-in frameworks, such as DITA or DocBook, can be viewed in the Document Type Configuration dialog box. However, there will be some differences with respect to what you see in the Oxygen XML Web Author user interface:
  1. Some actions are added using JavaScript code in the framework. They are present in the Oxygen XML Web Author toolbar but not visible in the Document Type Configuration dialog box.
  2. Some actions use an AuthorOperation that is not compatible with Oxygen XML Web Author. They are visible in the Document Type Configuration dialog box but they are not present in the Oxygen XML Web Author toolbar.
  3. Some actions are not compatible with Oxygen XML Web Author as in the previous case, but they are replaced with another action using JavaScript code in the framework, which is compatible. They will appear both in Oxygen XML Web Author and in the Document Type Configuration dialog box.

Customizing the Header Bar

If you embed Web Author in a web page, you may want to remove the header bar that displays the logo, the name of the file, and the name of the author. You can hide it using the hideAppBar() JavaScript API.

Customizing the Side Views

You can customize the side-views that appear in the editor by using the JavaScript API as described in the Customizing the Side Views tutorial.

Customizing the Theme

Although Web Author has a neutral theme, to better match the theme of your application, you can customize it by injecting a custom CSS file using JavaScript code from a plugin. The CSS file should also be served by your plugin using the WebappStaticResourcesFolder extension type.

Edit online

Control the State of Change Tracking

There are several ways to control the state of the Change Tracking feature.

Changing the Change Tracking State in the Administration Page

You can set its initial state in the Administration page (using the Change tracking initial state option). You can choose between:
  • Stored in document - When a document is initially opened in Web author, the change tracking state is set to on if the following processing instruction is found at the end of the document: <?oxy_options track_changes="on"?>.
  • Always On - The change tracking state is set to on when a document is opened in Web Author.
  • Always Off - The change tracking state is set to off when a document is opened in Web Author.

Changing the Change Tracking State Using a Flag

You can also use a trackChanges flag to control whether or not the Change Tracking feature is enabled when a documented is opened in Oxygen XML Web Author. The flag can be set in two possible ways:
  • In an embedded link that launches Web Author so that when a user clicks the constructed link, the documented is opened in Web Author with the Change Tracking feature enabled.
  • In a plugin. You can set this flag in your plugin's JavaScript code as a loading option like this:
    goog.events.listen(workspace, sync.api.Workspace.EventType.BEFORE_EDITOR_LOADED, function(e) {
  if (FORCED_ON_TRACK_CHANGES_CONDITION) {
    e.options.trackChanges = sync.api.change_tracking.ChangeTrackingInitialState.FORCED;
  } else if (FORCED_OFF_TRACK_CHANGES_CONDITION) {
    e.options.trackChanges = sync.api.change_tracking.ChangeTrackingInitialState.FORCED_OFF;
  } else if (TRACK_CHANGES_ENABLED_CONDITION) {
    e.options.trackChanges = sync.api.change_tracking.ChangeTrackingInitialState.ENABLED;
  } else if (TRACK_CHANGES_DEFAULT_CONDITION) {
    e.options.trackChanges = sync.api.change_tracking.ChangeTrackingInitialState.DEFAULT;
  }
});

    The possible values for the trackChanges flag and their meaning can be found here: Web Author API Documentation: Class - ChangeTrackingInitialState.

    You can start from our sample loading options setter plugin.

Changing the Change Tracking State Programmatically

To change the state of the change tracking feature after the document is loaded, you need to include code in your plugin's JavaScript code, similar to this:
// Assuming you have an 'editor' variable of type sync.api.Editor
var editingSupport = editor.getEditingSupport();
if (editingSupport.getType() === sync.api.Editor.EditorTypes.AUTHOR) {
  var manager = editingSupport.getChangeTrackingManager();
  if (!manager.isTrackingChanges()) {
    var am = editingSupport.getActionsManager();
    am.getActionById("Author/TrackChanges").actionPerformed(function(){
      am.refreshActionsStatus("Author/TrackChanges");
    });
  }
}
Edit online

Control the Behavior of the Enter Key

You can control the behavior of the Enter key. Normally the Enter key opens the content completion list, but you can set an option to make the Enter key work similar to the behavior in a normal word processor. The user can still open the content completion list by pressing CTRL+Enter.

There are several ways to control whether or not the content completion popup window is displayed when a user presses the Enter key:
  • You can use the Show content completion list when pressing Enter option in the General tab of the Administration page.

  • You can set the ccOnEnter property in a plugin (using the LoadingOptions type definition from the Workspace API.

    Possible values for the ccOnEnter property:
    • true - When the user presses the Enter key, the content completion list will be displayed.
    • false - When the user presses the Enter key, it will work similar to the behavior in a normal word processor. For example, a new paragraph will be inserted, or the element will be spilt, or the same element will be inserted.

    You can set this property in your plugin's JavaScript code like this:

goog.events.listen(workspace, 
sync.api.Workspace.EventType.BEFORE_EDITOR_LOADED, function(e) {
    if(non-technical-user) {
      e.options.ccOnEnter = 'false';
    }
  });
Tip: You can also use this property in an embedded link that launches Web Author so that when a user clicks the constructed link, the documented will be opened in Web Author with the Enter key working according to the value you set.
Edit online

Hiding the Breadcrumb

The main editing pane includes a breadcrumb stripe at the bottom of the pane that shows the hierarchical XML structure of the current document. It is a helpful tool for users that want to be able to visualize or navigate the XML element structure within a document. If your users do not have a need for this breadcrumb, it is possible to hide it in the interface.

To hide the breadcrumb, set the hideBreadcrumb property in a plugin (using the LoadingOptions type definition from the Workspace API).

Possible values for the hideBreadcrumb property are:
  • false - The breadcrumb is visible in the interface.
  • true - The breadcrumb is not displayed in the interface.
You can set this property in your plugin's JavaScript code like this:
goog.events.listen(workspace, 
sync.api.Workspace.EventType.BEFORE_EDITOR_LOADED, function(e) {
    e.options.hideBreadcrumb = 'true';
});
Tip: You can also use this property in an embedded link that launches Web Author so that when a user clicks the constructed link, the breadcrumb is not displayed.
Edit online

Controlling the Behavior of Drag/Drop Operations

By default, dragging a valid URL string and dropping it into the editor in Oxygen XML Web Author will automatically insert it as a link element for the particular document type you are working with. For example, in DITA it would insert an xref element.

If an HTML element that represents a file from a side-view or a CMS window is dragged, you can make Oxygen XML Web Author insert links to that file when the element is dropped in the editor. This can be done by writing JavaScript code that lets Oxygen XML Web Author know that the dropped element represents a reference to a file.

This code should set a listener on the dragstart event for the type of items that can be dragged. On the handler for the dragstart event, you can set the application/oxy-reference custom type to the event's dataTransfer object.

The value of this custom type needs to be a string before being added to dataTransfer.

The object must contain the following properties:
  • type - The reference type to insert. One of the following values:
    • FILE_REFERENCE - The URL points to an arbitrary file inside the same project.
    • IMAGE_REFERENCE - The URL points to an image.
    • WEB_REFERENCE - The URL points to an external resource.
    • XML_REFERENCE - The URL points to an XML file.
  • url - The OXY-URL that the reference points to.
An example of adding custom data on the dragstart event handler should look like this:
// type needs to be set to 'text' for IE only.
var type = 'application/oxy-reference'; 
e.dataTransfer.setData(type, JSON.stringify({ 
  url: 'http://example_url.com', 
  type: 'xml_reference' 
}));

To customize what element gets inserted when a link is dropped, one can use the ro.sync.ecss.extensions.api.AuthorExternalObjectInsertionHandler Java API.

Edit online

Hiding Specific Attributes

A CMS or an Oxygen XML Web Author customization can automatically manage some XML attributes, so the user cannot modify them. For example, a CMS can generate an @id attribute for each element that is used to link the element to the CMS database.

To hide such attributes from the Oxygen XML Web Author user interface, you can use the server-side ro.sync.ecss.extensions.api.attributes.AuthorAttributesDisplayFilter Java API.
Note: The attributes will still be visible in the text page. You can also remove the text page.