Edit online

The Oxygen SDK (Part 2: Frameworks)

Radu Coravu
Read time: 9 minute(s)

This is the second part of a blog post I started some time ago:

The Oxygen SDK (Part 1: Plugins).

There are two ways of customizing the application, by implementing a plugin or by implementing a framework:

https://www.oxygenxml.com/doc/ug-editor/topics/api_faq_plugin_framework_difference.html

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

If you are already using Oxygen for editing DITA, Docbook, XHTML or TEI documents you may notice that Oxygen knows how to validate these vocabularies and that it can propose content completion entries while you are editing. Also when you are editing in the Author visual editing mode you have lots of custom vocabulary-specific toolbar buttons which can be used to insert links, images, to manipulate tables and so on. This happens because each Oxygen installation comes with pre-bundled framework configurations for certain XML vocabularies that we consider to be more important for our users.

Knowing how to create and modify a framework/document type association configuration will benefit you in two ways:
  1. Create your own framework which adds editing support to Oxygen for certain specific XML vocabularies and then distribute it to your team.
  2. Customize an existing framework bundled with the installation (DITA, Docbook, etc) and change certain behaviors in it.

Our user manual contains a special step by step tutorial which explains how a new framework configuration (document type association) can be created and configured:

https://www.oxygenxml.com/doc/ug-editor/topics/authoring_customization.html

The Oxygen Preferences->Document Type Association page lists all detected frameworks (document type associations). Usually looking inside one of the pre-configured document type associations (eg: DITA) is a good place to start exploring what such a customization contains:
  1. Association rules - when one of these rules matches the opened XML document, Oxygen will associate it with the current document type association. The rules are pretty simple to compose, they refer to a certain root name, namespace, certain attributes set on the root and so on.
  2. Schema - specifies a grammar to be used to providing validation and content completion if the opened XML document does not refer directly to any particular gramar.
  3. Classpath - a list of JAR libraries which contain Java extensions for this specific framework.
  4. Author - contains all necessary support for editing the XML in the Author visual editing mode:
    • CSS - one or more CSS files to be used when rendering the XML. If you define alternate CSSs, you will be able to switch between them when editing. The user manual contains a list of supported CSS features and additional available extensions.
    • Actions - a list of actions specific for modifying the edited content. An action has a name, description, icons and shortcut key. It also has one or more activation contexts which depending on an XPath expression enable a certain operation be executed. A fair amount of basic operations are already available but you can create your custom operations.
    • Menu, Contextual menu and Toolbar - you can easily mount defined actions to the main document type menu, to the contextual menu or to the special Author toolbar(s).
    • Content Completion - add defined actions to the content completion window (shown when ENTER is pressed in the Author editor mode) or remove existing entries from the content completion window. You can for example replace some of the insert suggestions given by the association grammar with your own custom actions.
  5. Templates - points to folders which contain new file templates for this particular framework. These new file templates will be shown in the New wizard dialog.
  6. Catalogs contains a list of XML catalogs which will be used to indirectly solve various references (like references to schemas or other XML documents).
  7. Transformation may contains a predefined list of transformation scenarios which are available when you want to publish your opened XML document to various output formats.
  8. Validation may contain a predefined list of validation scenarios which are used to add complex multi-stage validation (with multiple engines) for the XML documents matching the document type association.
  9. Extensions - contains implementations of the available Java extensions which are used to provide further functionality for editing in the Author visual editing mode. Here's what some of the extensions do:
    • AuthorExtensionStateListener - provides a way to be notified when the XML was opened in the Author editing mode. You can then add all kinds of listeners and react to edit events done by the user. For example add a modification listener, send the edited content to an external spell checker engine and then add highlights in the content on invalid constructs.
    • AuthorExternalObjectInsertionHandler - reacts to drag and drop and copy/paste events containing with HTML content or resources. In the case of DITA for example this handler is responsible of the automatic conversion of HTML pasted from the browser to DITA content.
    • SchemaManagerFilter - filter and modify the insertion items detected from the associated grammar when editing XML content. For example even if the schema proposes certain elements as valid insertions at the caret offset, you can filter out and restrict the suggestions given by the associated schema (grammar).
    • StylesFilter - take control over the rendering styles for each node by adding this layer of Java customization over the styles provided by the associated CSSs.
    • AuthorSchemaAwareEditingHandler - handle special editing cases and provide fallbacks which keep the document in a valid state. For example if the user starts typing text between two paragraphs, the handler can automatically create a new paragraph.

You can create automated tests for your frameworks:

http://www.oxygenxml.com/doc/ug-oxygen/index.html#topics/automated-tests.html

and even debug their functionality:

https://www.oxygenxml.com/doc/ug-editor/topics/debug-sdk.html