Customizing the DITA Framework Using a Framework Extension Script

24 May 2021

Read time: 7 minute(s)

How to customize an existing framework (e.g. DITA) using a framework extension script.

All the validation, editing, and publishing support Oxygen has for a specific XML vocabulary is defined in a framework configuration. Oxygen comes bundled with such frameworks for popular XML vocabularies, such as DITA. A common use case is to make changes to these built-in frameworks, to tailor them according to specific requirements.

A framework extension script is an XML file that defines the changes to perform on a base framework. Suppose that you want to make the following changes to the DITA framework:

Customize the new document templates.
Change the Author mode rendering with a new CSS file.
Remove the Bold, Italic, Underline actions from the Author mode.
Add the Insert Note action to the toolbar.

Creating the Framework Extension Script

The easiest way to create such a script is to use the New document wizard and choose the Extend Framework Script or Create Framework Script template. Define it as an extension of the DITA framework through the @base attribute. Also, set a high priority, through the <priority> element, to make sure the framework will be picked in favor of the DITA one.

<script xmlns="http://www.oxygenxml.com/ns/framework/extend"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.oxygenxml.com/ns/framework/extend http://www.oxygenxml.com/ns/framework/extend/frameworkExtensionScript.xsd"
  base="DITA">
  <name>Custom DITA</name>
  <description>A custom DITA framework.</description>
  <priority>High</priority>
</script>

You need to save the script inside a framework directory (the same place as the *.framework file). For example, if you save it inside .../custom-frameworks/custom-dita/dita-script.exf, then you need to add .../custom-frameworks to the Additional frameworks directories list.

Note: Oxygen 23.1 or later will automatically detect the script and load the framework. If you want to use the framework in an older Oxygen XML Editor version that does not have support for these scripts, you can compile the script to obtain the *.framework file by using the Compile Framework Extension script action from the contextual menu or by running the scripts/compileFrameworkScript.bat external tool (available in the All Platforms distribution only).

Customizing the New Document Templates

The document templates appear when the user invokes the New... action. To add a new template, you need to do the following:

In the directory where the script is saved, create a new file (e.g. templates/My custom topic.dita). The content of the file represents the template's content.
In the script, specify the new template locations by adding this fragment inside the <script> element.
```
  <documentTemplates inherit="none">
    <addEntry path="${framework}/templates"/>
  </documentTemplates>
```

Note: In the example snippet above, the @inherit attribute is set to not inherit any of the document templates defined in the base framework.

Changing the Author Mode Rendering With a New CSS File

The author mode is driven by CSS rules. To add new rules, you need to:

Create a new CSS file in the directory where the script is saved. Give it a name (e.g. css/custom.css) and, for example, a rule to make titles red:
```
title {
  color:red;
}
```
In the script, specify the path to the new CSS by adding this fragment inside the <script> element.
```
  <author>
    <css>
      <addCss path="${framework}/css/custom.css"/>
    </css>
  </author>
```

Removing the Bold, Italic, Underline Actions From the Author Mode

An author action is just a configuration that describes which operation to use depending on the context. Each action has a unique ID. Suppose that you do not want Bold, Italic, and Underline actions from the built-in DITA framework because their markup is not semantic. After you inspect the actions preferences and we find out their IDs, you can filter them from all toolbars and menus by adding this fragment inside the <script> element.

<author>
    <authorActions>
      <removeAction id="bold"/>
      <removeAction id="italic"/>
      <removeAction id="underline"/>
    </authorActions>
  </author>

Adding the Insert Note Action to the Toolbar

The Insert Node action is already defined in the DITA framework, but it is not present on the toolbar. To add it to the toolbar, you need to:

Go to Options->Preferences, edit the DITA framework, and search in the Actions tab for the Insert Node action. Make note of its ID.

Edit the framework extension script and put the action in the toolbar by adding this fragment inside the <script> element.

  <author>
    <toolbars>
      <toolbar>
        <addAction id="insert.note" anchor="paragraph"/>
      </toolbar>
    </toolbars>
  </author>

Note: In this example, an action is used that is already present on the toolbar as an anchor. The new action is added to the toolbar after the action that inserts a paragraph.