Framework Extension Script File

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 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 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>

Setting the Initial Editing Mode

You can set the default editing mode that is loaded when a document is opened for the first time. For example, if the files are usually edited in the Author mode, you can set it as the initial page. For more details on the possible values, see Document Type Configuration Dialog Box - Initial Edit Mode.

Example: Setting the Initial Editing Mode to Author

<initialPage>Author</initialPage>

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 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>

Notice: Relative paths in the framework extension file are automatically resolved to the location of the script file.

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.

Sharing a Plugin Class Loader

If your framework uses the same JAVA extensions/classes as a plugin, it is recommended that they share the same classloader. This way, the common classes are loaded by only one Class Loader and they will both use the same static objects and have the ability to cast objects between one another.

<classpath parentClassLoaderID="com.oxygenxml.git.plugin"/>

Setting a Default Schema

You can specify a default schema for Oxygen XML Editor to use if an XML document does not contain a schema declaration and no default validation scenario is associated with it.

Example: Setting a Default XML Schema Relative to the Script Location

<defaultSchema schemaType="xmlschema" href="xsd/my-schema.xsd"/>

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>

Notice: Relative paths in the framework extension file are automatically resolved to the location of the script file.

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>

Notice: Relative paths in the framework extension file are automatically resolved to the location of the script file.

Adding New Transformation Scenarios and Removing Existing Ones

You can create new 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.

Example: Importing New Transformation Scenarios

The @href attribute from the <addScenarios> element is used to point to the location of the scenarios export file. Relative paths are resolved relative to the script's location. The ${framework} editor variable also resolves to the script's location. You can also remove any scenario inherited from the base framework or set the default scenario (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 create new validation scenarios and export them in one of the following locations:

The Configure Validation Scenario Dialog Box.
The Validation Tab.

Example: Importing New Validation Scenarios

The @href attribute from the <addScenarios> element is used to point to the location of the scenarios export file. Relative paths are resolved relative to the script's location. The ${framework} editor variable also resolves to the script's location. You can also remove any scenario inherited from the base framework or set the default scenario (the one used when another specific scenario is not specified).

<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;
}

Control How CSS Styles are Handled in the Author mode

The Author mode layout is driven by CSS rules. You can configure how CSS styles are handled in the framework by using the following attributes in the script file:

selectMultipleAlternateCSS

If set to true, any number of alternate CSS files can be activated and they will be applied like layers. If set to false, the alternate styles are treated like a main CSS style and only one can be selected at a time.

Example: Using the selectMultipleAlternateCSS Attribute in the Script

<css selectMultipleAlternateCSS="true"/>

mergeDocumentCSS

Controls how CSS files are handled if there are CSS styles specified in the document. If set to true, they will be merged with the CSS files from the framework. If set to false, they will be ignored.

Example: Using the mergeDocumentCSS Attribute in the Script

<css mergeDocument="true"/>

Example: Changing the styling in the author mode

We add a new CSS located in the new framework directory and we remove a CSS contributed by the base framework.

  <author>
    <css>
      <addCss path="css/style.css" />
      
      <removeCss path="${baseFramework}/resources/css/base.css"/>
    </css>
  </author>

Notice: Relative paths in the framework extension file are automatically resolved to the location of the script file.

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 action 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).

Replacing 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 want to keep one of these actions in all the GUI elements, but to perform differently in the new framework, just create an external author action with the same ID as the action to replace and save it in the specific subdirectory within your new framework directory.

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 Subtab.

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>