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.
<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.
<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.
<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>
- 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.
Setting a Default Schema
You can specify a default schema for Oxygen XML Web Author to use if an XML document does not contain a schema declaration and no default validation scenario is associated with it.
<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.
<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.
<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
- 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
@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
- The Configure Validation Scenario dialog box.
- The Validation tab in the document type configuration dialog box.
Example: Importing New Validation Scenarios
@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).<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.
<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>
*[class~='topic/title'] {
font-size:larger;
}
<author>
<css>
<addCss path="${framework}/pink.css" title="Pink titles" alternate="true"/>
</css>
</author>
*[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
<removeAction>
element:<author>
<authorActions>
<removeAction id="action.to.remove"/>
</authorActions>
</author>
<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.
<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>
Example: Creating a New Toolbar
@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
@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.@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.
<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>
<menu>
container.Example: Adding an Action in the Contextual Menu at a Specific Location
@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.@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.
<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.
<extensionPoints>
<extension
name="extensionsBundleClassName" <!-- the value of the name attribute
must be exactly this one -->
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.
<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>
<classpath xmlns="http://www.oxygenxml.com/ns/framework/extend">
<addEntry path="test.jar"/>
</classpath>