Wednesday, January 18, 2017

Your First Oxygen Add-on

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

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: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html.

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:
  1. A ZIP file containing the zipped framework folder.
  2. 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/versions/18.1/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/versions/18.1/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: http://blog.oxygenxml.com/2014/11/public-hosted-oxygen-plugin-and.html.

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.

3 comments:

  1. Can the xt:license element just contain character data?
    Isn't it possible to either put there a file reference, for content to be loaded from a file, or to somehow style its text content?
    Thanks
    Ruth

    ReplyDelete
  2. Maybe you can use xi:include to refer to the extra license file:
    <xt:license>
    <xi:include href="license.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/>
    </xt:license>

    ReplyDelete
  3. Thank you, it works fine

    ReplyDelete