Your First Oxygen Add-on

Read time: 4 minute(s)

A framework configuration provides validation, content completion, and visual editing support for a certain XML vocabulary.

Existing framework configurations that come bundled with Oxygen can be extended and modified. For example, the DITA framework configuration that adds support for editing DITA documents can be modified to remove existing actions, add custom actions, or modify many other behaviors: Document Type Extension Sharing.

One way of distributing framework configurations is by using Oxygen's add-on support: https://www.oxygenxml.com/addons.html. An add-on configuration is usually composed of only two files:

A ZIP file containing the zipped framework folder.

An add-on XML configuration file that references the zipped framework folder and defines various properties of the add-on. A small example can be seen below:

<xt:extensions xmlns:xt="http://www.oxygenxml.com/ns/extension"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.oxygenxml.com/ns/extension http://www.oxygenxml.com/ns/extension/extensions.xsd">
    <xt:extension id="dita-extension">
        <xt:location href="dita_extension.zip"/>
        <xt:version>1.0.0</xt:version>
        <xt:oxy_version>18.0+</xt:oxy_version>
        <xt:type>framework</xt:type>
        <xt:author>Radu Coravu</xt:author>
        <xt:name>DITA Extension which removes the bold action</xt:name>
        <xt:description xmlns="http://www.w3.org/1999/xhtml">
            This extension removes the bold action
        </xt:description>
        <xt:license>
<![CDATA[
Everybody's welcomed to use this
]]></xt:license>
    </xt:extension>
</xt:extensions>

In the add-on descriptor file you usually need to specify the following :

The ID of the extension.
The version of the add-on.
The minimum supported Oxygen version.
Author name.
Name and description of add-on.
Licensing details.

Changing the add-on version in the XML file will trigger notifications to the end user to install the new add-on. Therefore, you can modify the framework customization in a common location and change the add-on version to signal all end-users who have installed the add-on that a new version is available. More details about packing an add-on can be found here:https://www.oxygenxml.com/doc/ug-editor/topics/packing-and-deploying-addons.html#packing-and-deploying-addons.

If you want to test the small add-on I exemplified, you can find the sample add-on resources here:https://www.oxygenxml.com/forum/files/sample-add-on.zip.

Installing an add-on is straight-forward using the Install new add-ons dialog box from the Oxygen Help menu. You can add a reference to the add-on XML descriptor file that can reside either on the local hard drive or on a web server, and Oxygen will present all available add-ons: https://www.oxygenxml.com/doc/ug-editor/topics/installing-and-updating-add-ons.html

The add-ons support can also be used to install Oxygen plugins. Some of the public hosted Oxygen plugins and frameworks are also available as add-ons: Public hosted Oxygen Plugin and Framework Projects.

In conclusion, if you want to share Oxygen customizations with others, you should try the add-on approach, it is a better approach to manually distributing frameworks and plugins.