Edit online

Framework Extension Script File

The framework extension file is used to describe a new framework configuration. Optionally, you can extend an existing built-in framework configuration (such as DITA or DocBook) and then make additions and changes to it.

The easiest way to create such a file is to use the New document wizard in Oxygen XML Editor/Author and choose the Extend Framework Script or Create Framework Script template.

The following examples assume that the newly created framework extends a built-in one.

Basic Information

Once you have created a new script file, you need to:

Specify the name of the framework using the <name> element. Optionally, you can also add a description using the <description> element.
If you want to extend an existing framework (such as DITA or DocBook), specify the name of the extended framework using the @base attribute on the <script> element.
The <priority> element might be needed to instruct Oxygen XML Editor/Author to use this new framework instead of the one being extended or another framework that matches the same document.

Example: Extending the Built-in DITA Framework

<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>My custom DITA framework</name>
  <description>A custom framework based on the built-in DITA framework</description>
  <priority>High</priority>
</script>

Changing the Association Rules

Oxygen XML Editor/Author identifies the type of a document when the document matches at least one of the association rules.

Example: Instructing the Built-in Associations to Inherit None to Add Your Own

<associationRules inherit="none">
  <addRule rootElementLocalName="concept"/>
  <addRule fileName="test.xml"/>
</associationRules>

Changing the Classpath

The Classpath tab displays a list of folders and JAR libraries that hold implementations for API extensions, implementations for custom Author mode operations, various resources (such as stylesheets), and framework translation files. Oxygen XML Editor/Author loads the resources looking in the folders in the order they appear in the list.

Example: Customizing and Extending the Classpath Inherited From the Base Framework

  <classpath inherit="all">
    <!-- Contribute this resource before the ones inherited from the base framework
    because Oxygen loads the resources looking in the folders in the order they 
    appear in the list.
    -->
    <addEntry path="${framework}/resources_2x" position="before"/>
    
    <removeEntry path="${baseFramework}/refactoring/"/>
  </classpath>

Note: When removing entries with framework editor variables, take into consideration how they were added in the base framework.

An entry present in the base framework with the path ${framework}/file can be removed using an identical path or by using the ${baseFramework} variable: ${baseFramework}/file.
An entry present in the base framework with the path ${frameworkDir}/file can be removed using an identical path or by using the ${baseFrameworkDir} variable: ${baseFrameworkDir}/file.

Changing XML Catalogs

For cases where you need to reference the location of a schema file from a remote web location and an internet connection may not be available, an XML Catalog may be used to map the web location to a local file system entry.

Example: Customizing and Extending the XML Catalogs Inherited From the Base Framework

<xmlCatalogs inherit="all">
  <!-- Contribute this resource before the ones inherited from the base framework
    because Oxygen loads the resources looking in the folders in the order they 
    appear in the list.
    -->
  <addEntry path="${framework}/catalog.xml" position="before"/>
  
  <removeEntry path="${baseFramework}/oldCatalog.xml"/>
</xmlCatalogs>

Changing the Document Templates

You can create your own custom document templates or remove templates inherited from the base framework.

Example: Customizing and Extending the XML Catalogs Inherited From the Base Framework

<documentTemplates inherit="all">
  <!-- Contribute this resource before the ones inherited from the base framework
    to make them appear first in the list.
    -->
  <addEntry path="${framework}/newTemplates" position="before"/>
  
  <removeEntry path="${baseFramework}/oldTemplates"/>
</documentTemplates>

Adding New Transformation Scenarios and Removing Existing Ones

You can import newly created transformation scenarios and export them in one of the following locations:

The Transformation Scenarios view.
The Configure Transformation Scenario(s) dialog box.
The Transformation tab in the document type configuration dialog box.

Example: Importing New Transformation Scenarios

The @href attribute from the <addScenarios> element is used to point to the location of the scenarios export file. You can also remove any scenario inherited from the base framework as well as setting the default scenarios (the one used when another specific scenario is not specified).

<transformationScenarios>
  <addScenarios href="scenarioExport.scenarios"/>
  <removeScenario name="DITA HTML5"/>
  <defaultScenarios>
    <name>DITA</name>
    <name>XML</name>
  </defaultScenarios>
</transformationScenarios>

Adding New Validation Scenarios and Removing Existing Ones

You can import newly created validation scenarios and export them in one of the following locations:

The Configure Validation Scenario dialog box.
The Validation tab in the document type configuration dialog box.

Example: Importing New Validation Scenarios

<validationScenarios>
  <addScenarios href="validationScenarioExport.scenarios"/>
  <removeScenario name="DITA"/>
  <defaultScenarios>
    <name>DITA Validation</name>
    <name>XML Validation</name>
  </defaultScenarios>
</validationScenarios>

Customizing the Author Mode Through New CSS Files

The Author mode layout is driven by CSS rules. To customize it, you need to create new CSS files and add them in the new framework.

Example: Using Larger Fonts in Titles

<author>
    <css>
      <removeCss path="${framework}/base.css"/>
      <!-- 
        Adding CSS after the ones in the base gives the opportunity to 
        override rules from previous CSSs. 
      -->
      <addCss path="${framework}/titles.css" position="after"/>
    </css>
  </author>

The ${framework}/titles.css file contains a rule like this:

*[class~='topic/title'] {
  font-size:larger;
}

Example: Creating an Alternate CSS That Activates When the User Selects it in the Styles Menu

  <author>
    <css>
      <addCss path="${framework}/pink.css" title="Pink titles" alternate="true"/>
    </css>
  </author>

The ${framework}/pink.css file contains a rule like this:

*[class~='topic/title'] {
  color:#FF1493;
}

Defining Author Actions for the New Framework

Create external author actions, save them in a specific subdirectory of your particular framework directory, and they will be loaded automatically.

Removing Author Actions from the Base Framework

Suppose that the base framework configuration defines some author actions that are added in the main menu, contextual menu, toolbar, or content completion window. If you do not want to inherit one of these actions in the new framework and you also want to remove it from all the GUI elements, you can use the <removeAction> element:

<author>
  <authorActions>
    <removeAction id="action.to.remove"/>
  </authorActions>
</author>

Note: If the new framework has an external author actions with the same ID as one of the actions specified in a <removeAction> element, the action will not be removed from the GUI elements (menus, toolbars, content completion window).

Author Toolbar Configuration

The Author mode-specific toolbars for the new framework can be customized by:

Adding or removing actions from toolbars.
Changing toolbar groups by adding or removing actions.
Creating new toolbars and action groups.

Example: Customizing the Toolbar

  <author>
    <toolbars>
      <toolbar>

        <!-- Remove an action inherited from the base framework. -->
        <removeAction id="bold"/>
        
        <!-- Insert an action into an existing group -->
        <group name="${i18n(link)}">
          <addAction id="insert.note"/>
        </group>
        
        <!-- Add actions, separators and new groups-->
        <separator/>
        <addAction id="insert.note"/>
        
        <group name="New group">
          <addAction id="insert.note"/>
          <addAction id="insert.table"/>
        </group>
      </toolbar>
    </toolbars>
  </author>

Note: If you create a toolbar or group configuration and a toolbar/group with the same name already exists in the base framework, you will change the one inherited instead of creating a new one. You can inspect the names of the existing toolbars/groups inherited from the base framework in the Toolbar tab.

Example: Creating a New Toolbar

A new toolbar is created if the @name attribute does not match a toolbar inherited from the base.

<author>
    <toolbars>
      <toolbar name="Extra Toolbar">
        <!-- Add actions, separators and new groups-->
        <separator/>
        <addAction id="insert.note"/>
        
        <group name="New group">
          <addAction id="insert.note"/>
          <addAction id="insert.table"/>
        </group>
      </toolbar>
    </toolbars>
  </author>

Example: Adding an Action in the Toolbar at a Specific Location

You can insert items (actions or groups) relative to other items already present in the toolbar because they were inherited from the base framework configuration. The @anchor attribute specifies either the ID of an action or the name of a group already present in the toolbar and the @position attribute specifies whether the new item should be added before or after it.

Note: If the @anchor attribute is missing, the entries will be added either first or last, according to @position value.

      <toolbar>
        <addAction id="insert.note" anchor="bold" position="before"/>
        
        <group name="Table menu" anchor="${i18n(link)}" position="after">
          <addAction id="insert.table"/>
        </group>
      </toolbar>

Author Menu and Contextual Menu Configuration

The Author mode-specific menus for the new framework can be customized by:

Adding or removing actions and submenus.
Changing existing submenus by adding or removing actions.

Example: Customizing the Contextual Menu

    <contextualMenu>
      <!-- Add new actions and submenu -->
      <separator/>
      <addAction id="insert.table"/>
      <submenu name="Other actions">
        <addAction id="insert.note"/>
      </submenu>
      
      <!-- Contribute to an existing submenu -->
      <submenu name="${i18n(section)}">
        <addAction id="paragraph"/>
      </submenu>
      
      <!-- Remove a submenu inherited from the base framework. -->
      <removeSubmenu name="${i18n(link)}"/>
    </contextualMenu>

Note: The framework main menu is configured similarly, inside a <menu> container.

Tip: You can inspect the names of the submenus inherited from the base framework in the Contextual Menu subtab and Menu subtab.

Example: Adding an Action in the Contextual Menu at a Specific Location

You can insert new actions and submenus relative to other actions and submenus already present in the menu because they were inherited from the base framework configuration. The @anchor attribute specifies the ID of an Author mode action or a name of a submenu already present in the menu and the @position attribute specifies whether the new action should be added before or after it.

Note: If the @anchor attribute is missing, the entries will be added either first or last, according to @position value.

    <contextualMenu>
      <addAction id="insert.note" anchor="edit.image.map" position="before"/>
      
      <submenu name="Table menu" anchor="${i18n(insert)}" position="after">
        <addAction id="insert.table"/>
      </submenu>
    </contextualMenu>

Configuring the Content Completion in Author Mode

You can replace content completion entries obtained from the associated schema with Author mode actions.

In the <authorActions> container, you can specify the Author mode actions to be contributed. Optionally, you can mark them as a replacement for an existing schema proposal with the @replacedElement attribute.

The <schemaProposals> element allows you to remove proposals detected from the associated schema through the <removeProposal> element. If some proposals were removed in the base framework configuration and you want them re-added, you can do so through the <addProposal> element.

Example: Customizing the Content Completion Assistant

<contentCompletion>
  <authorActions>
    <addAction id="insert.note" replacedElement="note" inCCWindow="true"/> 
  </authorActions>
  
  <schemaProposals>
    <removeProposal renderName="table"/>
    
    <!-- The base framework removed the "list" element proposal. We want it back... -->
    <addProposal renderName="list"/>
  </schemaProposals>
</contentCompletion>

Using Framework Extension Points

The Extensions tab specifies implementations of Java interfaces used to provide advanced functionality to the document type. Libraries that contain the implementations must be present in the classpath of your framework. The Javadoc available at https://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ contains details about how each API implementation functions.

Example: Setting a Custom Extensions Bundle

<extensionPoints>
  <extension 
    name="extensionsBundleClassName" 
    value="ro.sync.ecss.extensions.dita.map.DITAMapExtensionsBundle"/>
</extensionPoints>

Reusing Parts of the Script Using XInclude

Elements in the script can be specified in dedicated files that can then be referenced using XInclude in the script.

Example: Using XInclude to Reference Elements in the Script

<script xmlns="http://www.oxygenxml.com/ns/framework/extend">
    <name>New framework</name>
    <xi:include href="classpath.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</script>

Where the referenced classpath.xml has this content:

<classpath xmlns="http://www.oxygenxml.com/ns/framework/extend">
    <addEntry path="test.jar"/>
</classpath>