Edit online

Migrating a Framework from Oxygen XML Editor/Author to Web Author

Frameworks developed for Oxygen XML Editor/Author have a high degree of compatibility with Oxygen XML Web Author. However, in some cases, additional work is required to make the framework compatible with both products.

General Recommendations

You can use the Web Author Test Server add-on to test your framework in both products with minimal overhead.

Note: It is always useful to check out the server log. It can be found in the plugin's folder in: tomcat/logs/oxygen.log.

Document Styles

The CSS styles used to render the document in the desktop application can be re-used in Web Author, although there are some limitations.

Toolbar and Contextual Menu Actions

Actions in Oxygen XML Web Author can be specified in two ways:

In the Document Type Configuration dialog box as a list of operation modes, each mode having an associated AuthorOperation.

If the corresponding AuthorOperation is not marked as compatible with Web Author, the action is not available for the users. Sometimes this is just a matter of annotating your custom Java class. In other cases (for example, when the AuthorOperation is used to show a custom Java Swing dialog box), it has to be re-implemented in JavaScript.
Implemented in the framework's JavaScript code.

The actions registered from JavaScript code can overwrite an action with the same ID defined in the Document Type Configuration dialog box. The built-in frameworks already implement such actions that insert a table, image, or a link.

Some of the toolbar actions may not appear in Web Author. The most common reason is that the toolbar actions use a custom AuthorOperation that is not marked as compatible with Web Author.

This is how the toolbar structure is built:

The default structure of the toolbar is defined in the *.framework file and is common with the one in the desktop editor. You can visualize it using the Document Type Configuration dialog box.
The client-side component of Web Author retrieves this configuration using an HTTP request to something like ./rest/VERSION/actions/actionsConfig/docNNN.NNN. Actions that are not compatible are removed from this configuration. You can check it in the browser's Dev Tools Network tab.
The framework's JavaScript code overrides the configuration of the toolbar. If you are extending a framework, the JavaScript code of the base framework can also modify the configuration of the toolbar.
Note: If you are extending the built-in DITA Map framework, make sure that the name of the framework extension contains the ditamap word. Otherwise, actions such as Insert New Topic Reference will not appear.
When the contextual menu is shown, actions that are not enabled at a specific position are not shown.

Notes:

If the configured activation XPath evaluates to false at the current cursor position, it does not disable the actions on the Web Author toolbar, but when the user tries to invoke an action, the operation will not be executed (if the XPath evaluates to false) and the user will be notified that the action is not available at that location.
If you configure an action that inserts an element by using InsertFragmentOperation, it is better to use true for the XPath. The editor will try to find a valid position near the current cursor position to insert the element.
If the action modifies a specific type of element at the cursor position (e.g. an image), you can control the disabled state of the action by replacing it with one implemented in JavaScript with the isEnabled method overridden.

New Document Templates

When editing a DITA map, there is a

Insert New DITA Resource toolbar button that opens a dialog box where you can choose the type of DITA document to create and inserts a reference to it at the current position within the map. The templates that are listed include:

Templates that have type=dita specified in its .properties file.
Templates that do not have a type specified in its .properties file.
Templates that do not have a .properties file.

If you want to hide a particular template from appearing in the dialog box, you should modify the .properties file for the particular template and make sure it has a type and that the type is not set to dita. For more details about configuring the .properties file for a template, see Customizing Document Templates.