All About Editor Variables

3 Feb 2020

Read time: 10 minute(s)

In various places in the Oxygen XML Editor application there is support for expanding variables. These variables/macros usually take the form ${variableName} and are expanded by the application dynamically when necessary. A list with all supported editor variables can be found in the user's manual: https://www.oxygenxml.com/doc/ug-editor/topics/editor-variables.html. I will enumerate below all major contexts in which using such editor variables may prove useful:

Transformation Scenarios

Most transformation scenario types have lists of parameters and fields where you can configure the place where the output should be saved. You can use editor variables in these places to make the transformation scenario portable and thus to be able to share it with your colleagues. Here are some examples:

XML with XSLT based transformation scenario types: If you edit such a scenario and go to the Output tab you can specify the Save as field to use editor variables like this ${cfd}/${cfn}.html which will get expanded to use the current XML document folder and file name but with a different extension when the output of the transformation gets saved on disk. You can also use editor variables like ${date()} to save the output file name using the current date: ${cfd}/${cfn}-${date(yyyy-MM-dd)}.html.; The XSLT tab already uses the ${currentFileURL} editor variable in order to be applied on any XML document opened in the editor area. The Parameters list allows you to specify XSLT parameters with values which may contain editor variables which will be expanded by the application before the transformation is run. For example as value for a parameter you can use an ${ask()} editor variable which will end up requesting the value from the end user when the transformation is started: ${ask('New Parameter Value', generic, 'default')}.

ANT based transformation scenario types: In the Parameters tab you can add new parameters which will be passed to the ANT build file. Values for such parameters can also contain editor variables. You can add for example a parameter called currentXMLDocument with value ${pd}/specificFileName.xml if you want a path to a specific XML file in the current XML project to be passed to the ANT build file as a variable. Again you can use ${ask()} editor variable which will end up requesting the value from the end user when the transformation is started.

DITA Open Toolkit transformation scenario types: DITA Open Toolkit transformation scenarios are based on ANT so the previous tips apply. In addition you can use the ${rootMapFile} related editor variables which gets expanded to the current root map. For example in the Filters tab I can specify the reference to the DITAVAL file like this: ${rootMapDir}/filter.ditaval to refer to the filter relative to the folder where the current root map is published.; You can also extract the root DITA Map file name using the ${xpath_eval()} editor variable: ${xpath_eval(tokenize('${rootMapURL}', '/')[last()])}.

New File Templates

You can create your own new file templates and have them use when the Oxygen XML Editor File->New dialog wizard is used to create new documents: Sharing New Custom File Templates for a Specific Vocabulary.

The content of these new file templates can have inside editor variables which are automatically expanded when a new XML document is created. For example a new file template like this:

<topic id="topic_${id}">
    <title>${caret}</title>
    <prolog>
        <author>${ask('Author Name?', generic, 'default')}</author>
    </prolog>
    <body>
        <p></p>
    </body>
</topic>

makes use of multiple editor variables:

The ${id} editor variable expands to an unique short ID value containing alphanumerical characters. You can also use the ${uuid} editor variable to generate a truly unique but longer ID value.
The ${caret} editor variable marks the position where the caret will be placed after the XML document created from the new file template is initially opened.
The ${ask} editor variable will ask the end user to provide the name of the author and will get expanded in the XML content. You can also use ${answer} editor variables to use the same answer to the ${ask} editor variable in multiple places.

Code Templates

Oxygen XML Editor's code templates support allows you to define small pieces of XML content which can later be inserted by pressing the Ctrl-Space keyboard shortcut (or ENTER in the Author visual editing mode). Code templates can also contain editor variables which get expanded when the code template is used. Examples:

You can use the ${selection} editor variable to surround the current selected content in the main editing area inside the code template:
```
<em>${selection}</em>
```
The ${caret} editor variable allows you to precisely choose a place for the caret after the code template is inserted:
```
<ph keyref="oxygen"/>${caret}
```
In the example above the caret will be placed after the inserted element when the code template is chosen.
The ${ask} editor variable will trigger the application to ask for a value to insert in a particular place of the code template:
```
<problem reason="${ask('Reason?', radio, ('lost':'lost';'illegible':'illegible';'omitted':'omitted';), 'lost')}"/>
```
In the example above when the code template is chosen, the end user will need to choose the reason in a dialog showing a combo box of possible choices and the chosen reason will be expanded in the code template before being inserted in the XML content.

Custom Author Actions

Oxygen XML Editor framework configurations allow defining custom actions for the Author visual editing mode and then contributing these actions to framework-specific toolbars and menus. An example of implementing such a custom action can be found here: Implementing a Custom Author Action to Split a Table.

In some of the default operations that you can use in a custom Author action (for example in the InsertFragmentOperation) you can use editor variables.

External Tools

You can run external command line scripts from Oxygen XML Editor by configuring external tools in the Preferences page. The defined external tools allow using editor variables like ${pd} to access the current project folder and the editor variables will be automatically expanded before the external tool is invoked.

Custom Editor Variables

You can define your custom editor variables in the application Custom Editor Variables preferences page. A custom editor variable can contain as values other editor variables and can be used in all places where a predefined editor variable is.

You can use Oxygen XML Editor's API to provide custom editor variables and their expanded values using custom Java or Javascript code. For example this plugin adds support for a new ${clipboard} editor variable.