Customizing Oxygen XML Editor (Overview)

Let's assume you just bought Oxygen and want to customize it in order to better suit your team's workflow or to add support for your custom XML vocabulary. I will attempt to provide a set of use cases along with indications and useful links about what customization should be done in order to cover each use case:

Add support for editing a specific XML vocabulary

This kind of support usually should include:

• New file templates.
• Validate opened XML documents according to a custom schema.
• Provide custom CSS to be used in the Author visual editing mode.
• Provide custom toolbar, menu, and contextual menu actions to be used in the Author visual editing mode.

Such support is done using a document type/framework configuration: http://blog.oxygenxml.com/2014/08/the-oxygen-sdk-part-2-frameworks.html.

Customize the existing support for a specific XML vocabulary

Oxygen comes with pre-configured framework configurations for the most commonly used XML standards such as DITA, Docbook, TEI, or XHTML. You may want to customize the existing configuration for one of these vocabularies and share the customization with others. Such customizations may include:

• Provide custom file templates: http://blog.oxygenxml.com/2015/12/sharing-new-custom-file-templates-for.html.
• Provide a custom CSS layer: http://blog.oxygenxml.com/2016/10/customizing-dita-visual-editing.html.
• Provide custom Schematron validation rules: http://blog.oxygenxml.com/2017/02/sharing-schematron-validation-rules.html.
• Provide custom actions or modify the existing actions.

All of these customizations can be done by extending the existing framework configuration and then sharing the extension: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html.

Provide custom settings

You may want to provide all members of the team with a fixed set of options: http://blog.oxygenxml.com/2015/11/sharing-application-settings.html.

Modify the application appearance or behavior using plugins

Oxygen plugins can be used to:

• Contribute custom views and toolbars for the entire application.
• Filter out existing views or toolbar actions.
• Contribute a fixed set of options/settings to the application.
• Register various listeners and be notified when a document is opened, closed, saved, and so on.
• Use the existing API to make changes to the opened documents.

A more detailed overview of Oxygen plugins can be found here: http://blog.oxygenxml.com/2013/11/the-oxygen-sdk-part-1-plugins.html.

The most popular plugin extension is the Workspace Access plugin extension: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/concepts/workspace-access-plugin.html. This extension is notified when the application starts and can contribute custom views, custom main menu items, custom main toolbar actions, or add listeners for various document-related changes.

There is also a JavaScript-based workspace access plugin extension that can use JavaScript to call our Java API: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/concepts/workspace-access-plugin-js.html.

A set of sample plugins built with the JavaScript-based extension can be found here: https://github.com/oxygenxml/wsaccess-javascript-sample-plugins.

Our Maven-based SDK can be used to develop both plugins and framework Java customizations: https://www.oxygenxml.com/oxygen_sdk_maven.html.

Sharing Schematron Validation Rules

Custom Schematron rules are a great way to ensure consistency for the edited XML structure, especially when there is a large team working on the same set of documents. You can use Schematron for numerous use cases. For example, to make sure that certain elements are not used at all, to impose restrictions on the amount of text for an element, or to impose restrictions on certain elements based on various attribute values or text content set in other elements. Furthermore, you can define quick fixes for each Schematron rule to give the technical writer proposed solutions for the reported problem. In a previous blog post, I described how we use Schematron rules for our Oxygen User's Manual to impose restrictions when editing DITA content: http://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html.

Once you define the Schematron rules, they can be shared with the other members of your team via a document type framework configuration: http://blog.oxygenxml.com/2014/08/the-oxygen-sdk-part-2-frameworks.html.

In this post, I'm going to provide some precise steps to share a set of Schematron rules with a DITA framework extension.

Instead of making changes directly to the DITA framework configuration folder (located in OXYGEN_INSTALL_DIR\frameworks\dita) and distributing it, you can choose to extend the DITA framework and distribute the extension. This way, you will benefit from new functionality added to the base framework in newer versions of Oxygen and you can still use your customizations.

The following steps describe how you can extend a DITA framework that contains an additional Schematron rules file:

1. Create a folder structure (for example, custom_frameworks/dita-extension) somewhere on your local disk, in a place where you have full write access.
2. In that new folder structure, create another folder (custom_frameworks/dita-extension/rules) that will contain all of your custom Schematron files.
3. Create a new ISO Schematron file (for example, additionalRules.sch) that contains the additional rules you want to impose. For example, the following Schematron rule reports an error if the @scale attribute is used on an image:

   <schema xmlns="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2"
       xmlns:sqf="http://www.schematron-quickfix.com/validator/process">
       <pattern>
           <rule context="*[contains(@class, ' topic/image ')]">
               <assert test="not(@scale)">
                   Dynamically scaled images are not properly displayed, you
                   should scale the image with an image tool and keep it within
                   the recommended with and height limits.
               </assert>
           </rule>
       </pattern>
   </schema>

4. In the Document Type Association / Locations preferences page, add the path to your custom_frameworks folder in the Additional frameworks directories list. Click OK or Apply in the Preferences dialog to save your changes.
5. In the Document Type Association preferences page, select the DITA document type configuration and use the Extend button to create an extension for it.
6. Give the extension a custom name (for example, DITA - Custom), then change its Storage option to External, and then save it to a path such as: path/to/.../custom_frameworks/dita-extension/dita-extension.framework.
7. Make whatever changes you desire to the extension, go to the Validation tab, edit the default DITA validation scenario, and add an extra validation stage to it (a stage that uses your custom Schematron schema). More details about validation scenarios can be found here: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/tasks/dg-validation-scenarios.html.
8. Click OK to close the dialog box and then either OK or Apply to save the preferences changes.

After you perform the steps above, in the dita-extension folder you will have a fully functioning framework extension that can be shared with others.

There are several methods for sharing the framework and you can read about them here: https://www.oxygenxml.com/doc/versions/18.1/ug-editor/topics/author-document-type-extension-sharing.html.

After your team members install the framework, they can check the Document Type Association preferences page to make sure the framework is present in the list of Document Types and that it appears before the bundled DITA framework (meaning that it has higher priority).

You can use the framework extension mechanism to customize numerous aspects of the DITA functionality in Oxygen. For example, you can remove various elements from the content completion list: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html. Or you can distribute custom new file templates: http://blog.oxygenxml.com/2015/12/sharing-new-custom-file-templates-for.html.