Edit online

Editor Variables

An editor variable is a shorthand notation for context-dependent information, such as a file or folder path, a time-stamp, or a date. It is used in the definition of a command (for example, the input URL of a transformation, the output file path of a transformation, or the command line of an external tool) to make a command or a parameter generic and re-usable with other input files. When the same command is applied to multiple files, the notation is expanded at the execution of the command so that the same command has different effects depending on the actual file.

Oxygen XML Editor includes a variety of built-in editor variables. You can also create your own custom editor variables by using the Custom Editor Variables preferences page.

Editor variables are evaluated and automatically expanded in many places in the application, when:

Creating new documents from file templates.
Inserting code templates in the Text or Author editor modes.
Running custom configured External Tools.
Executing predefined Built-in Author Mode Operations that have editor variables given as parameter values.
Running validation scenarios that use editor variables inside to reference various resources.
Executing transformation scenarios (of type ANT, DITA-OT, XSLT, etc.) that have editor variables set as parameter values or as values for references to various resources.
Expanding CSS imports for editing in the Author visual editing mode.
Using specific Java API UtilAccess.expandEditorVariables(String, URL) from plugins and framework extensions.

You can use the following editor variables in Oxygen XML Editor commands of external engines or other external tools, and in various places in the application, such as in transformation scenarios, Author mode operations, and validation scenarios:

${activeConditionSet} - Current active profiling condition set name. If there is no active condition set, the variable will be replaced with an empty string.
${af} - The local file path of the ZIP archive that includes the currently edited document.
${afd} - The local directory path of the ZIP archive that includes the currently edited document.
${afdu} - The URL path of the directory of the ZIP archive that includes the currently edited document.
${afn} - The file name (without parent directory and without file extension) of the zip archive that includes the currently edited file.
${afne} - The file name (with file extension, for example .zip or .epub, but without parent directory) of the zip archive that includes the currently edited file.
${afu} - The URL path of the ZIP archive that includes the currently edited document.

${answer(@id)} - Used in conjunction with the ${ask} editor variable. The @id parameter is required and identifies the answer from the ${ask} editor variable with the same ID.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="topic_lcf_1c4_tdb">
    <title></title>
    <body>
        <data name="${ask('Set a data name', String, 'name', @name)}"></data> 
        <p>The name is: ${answer(@name)}</p>
    </body>
</topic>

${ask('message', type, ('real_value1':'rendered_value1'; 'real_value2':'rendered_value2'; ...), 'default_value', @id)} - To prompt for values at runtime, use the ask('message', type, ('real_value1':'rendered_value1'; 'real_value2':'rendered_value2'; ...), 'default-value'') editor variable. You can set the following parameters:

'message' - The displayed message. Note the quotes that enclose the message.
'default-value' - Optional parameter. Provides a default value.
@id - Optional parameter. Used for identifying the variable to reuse the answer using the ${answer(@id)} editor variable.

type - Optional parameter (defaults to generic), with one of the following values:

Note: The title of the dialog box will be determined by the type of parameter and as follows:

For url and relative_url parameters, the title will be the name of the parameter and the value of the 'message'.
For the other parameters listed below, the title will be the name of that respective parameter.
If no parameter is used, the title will be "Input".

Notice: Editor variables that are used within a parameter of another editor variable must be escaped within single quotes for them to be properly expanded. For example:

${ask( 'Provide a date',generic,'${date(yyyy-MM-dd'T'HH:MM)}')}


Parameter
generic (default)	Format: ${ask('message', generic, 'default')}
	Description: The input is considered to be generic text that requires no special handling.
	Example: ${ask('Hello world!')} - The dialog box has a Hello world! message displayed. ${ask('Hello world!', generic, 'Hello again!')} - The dialog box has a Hello world! message displayed and the value displayed in the input box is 'Hello again!'.
url	Format: ${ask('message', url, 'default_value')}
	Description: Input is considered a URL. Oxygen XML Editor checks that the provided URL is valid.
	Example: ${ask('Input URL', url)} - The displayed dialog box has the name Input URL. The expected input type is URL. ${ask('Input URL', url, 'http://www.example.com')} - The displayed dialog box has the name Input URL. The expected input type is URL. The input field displays the default value http://www.example.com.
relative_url	Format: ${ask('message', relative_url, 'default')}
	Description: Input is considered a URL. This parameter provides a file chooser, along with a text field. Oxygen XML Editor tries to make the URL relative to that of the document you are editing. Note: If the $ask editor variable is expanded in content that is not yet saved (such as an untitled file, whose path cannot be determined), then Oxygen XML Editor will transform it into an absolute URL.
	Example: ${ask('File location', relative_url, 'C:/example.txt')} - The dialog box has the name 'File location'. The URL inserted in the input box is made relative to the currently edited document location.
password	Format: ${ask('message', password, 'default')}
	Description: The input is hidden with bullet characters.
	Example: ${ask('Input password', password)} - The displayed dialog box has the name 'Input password' and the input is hidden with bullet symbols. ${ask('Input password', password, 'abcd')} - The displayed dialog box has the name 'Input password' and the input hidden with bullet symbols. The input field already contains the default abcd value.
combobox	Format: ${ask('message', combobox, ('real_value1':'rendered_value1';...;'real_valueN':'rendered_valueN'), 'default')}
	Description: Displays a dialog box that offers a drop-down menu. The drop-down menu is populated with the given rendered_value values. Choosing such a value will return its associated value (real_value). Note: The list of 'real_value':'rendered_value' pairs can be computed using ${xpath_eval()}. Note: The 'default' parameter specifies the default-selected value and can match either a key or a value.
	Example: ${ask('Operating System', combobox, ('win':'Microsoft Windows';'macos':'macOS';'lnx':'Linux/UNIX'), 'macos')} - The dialog box has the name 'Operating System'. The drop-down menu displays the three given operating systems. The associated value will be returned based upon your selection. Note: In this example, the default value is indicated by the osx key. However, the same result could be obtained if the default value is indicated by macOS, as in the following example: ${ask('Operating System', combobox, ('win':'Microsoft Windows';'macos':'macOS';'lnx':'Linux/UNIX'), 'macOS')} ${ask('Mobile OS', combobox, ('ios':'iOS';'and':'Android'), 'Android')} ${ask('Mobile OS', combobox, (${xpath_eval(for $pair in (['ios', 'iOS'], ['and', 'Android']) return "'" \|\| $pair?1 \|\| "':'" \|\| $pair?2 \|\| "';")}), 'ios')}
editable_combobox	Format: ${ask('message', editable_combobox, ('real_value1':'rendered_value1';...;'real_valueN':'rendered_valueN'), 'default')}
	Description: Displays a dialog box that offers a drop-down menu with editable elements. The drop-down menu is populated with the given rendered_value values. Choosing such a value will return its associated real value (real_value) or the value inserted when you edit a list entry. Note: The list of 'real_value':'rendered_value' pairs can be computed using ${xpath_eval()}. Note: The 'default' parameter specifies the default-selected value and can match either a key or a value.
	Example: ${ask('Operating System', editable_combobox, ('win':'Microsoft Windows';'macos':'macOS';'lnx':'Linux/UNIX'), 'macos')} - The dialog box has the name 'Operating System'. The drop-down menu displays the three given operating systems and also allows you to edit the entry. The associated value will be returned based upon your selection or the text you input. ${ask('Operating System', editable_combobox, (${xpath_eval(for $pair in (['win', 'Microsoft Windows'], ['macos', 'macOS'], ['lnx', 'Linux/UNIX']) return "'" \|\| $pair?1 \|\| "':'" \|\| $pair?2 \|\| "';")}), 'ios')}
radio	Format: ${ask('message', radio, ('real_value1':'rendered_value1';...;'real_valueN':'rendered_valueN'), 'default')}
	Description: Displays a dialog box that offers a series of radio buttons. Each radio button displays a 'rendered_value and will return an associated real_value. Note: The list of 'real_value':'rendered_value' pairs can be computed using ${xpath_eval()}. Note: The 'default' parameter specifies the default-selected value and can match either a key or a value.
	Example: ${ask('Operating System', radio, ('win':'Microsoft Windows';'macos':'macOS';'lnx':'Linux/UNIX'), 'macos')} - The dialog box has the name 'Operating System'. The radio button group allows you to choose between the three operating systems. Note: In this example, `macOS` is the default-selected value and if selected, it would return macos for the output. ${ask('Operating System', radio, (${xpath_eval(for $pair in (['win', 'Microsoft Windows'], ['macos', 'macOS'], ['lnx', 'Linux/UNIX']) return "'" \|\| $pair?1 \|\| "':'" \|\| $pair?2 \|\| "';")}), 'ios')}

${author.name} - Expands to the current author name that is set in the Review preferences page.
${caret} - The position where the cursor is located. This variable can be used in a code template, in Author mode operations, or in a selection plugin.
Note: The ${caret} editor variable is available only for parameters that take XML content as values. It is replaced with the ${UNIQUE_CARET_MARKER_FOR_AUTHOR} macro. The default Author operations process this macro and position the cursor at the designated offset.
Note: The ${caret} editor variable can be used for setting a fixed cursor position inside an XML fragment. To set the cursor position depending on the fragment inserted in the document, you can use AuthorDocumentFilter and inside the insertFragment(AuthorDocumentFilterBypass, int, AuthorDocumentFragment) method, use the AuthorDocumentFragment.setSuggestedRelativeCaretOffset(int) API on the given fragment.
${cf} - Current file as file path, that is the absolute file path of the currently edited document.
${cfd} - Current file folder as file path, that is the path of the currently edited document up to the name of the parent folder.
${cfdu} - Current file folder as URL, that is the path of the currently edited document up to the name of the parent folder, represented as a URL.
${cfn} - Current file name without the extension and parent folder. The current file is the one currently open and selected.
${cfne} - Current file name with extension. The current file is the one currently open and selected.
${comma} - Used to display a comma when the actual comma symbol would be considered part of some sort of instruction or delimiter.
${configured.ditaot.dir} - The default directory of the DITA Open Toolkit distribution, as configured in the DITA preferences page.
${cp} - Current page number. Used to display the current page number on each printed page in the Editor / Print Preferences page.
${currentFileURL} - Current file as URL, that is the absolute file path of the currently edited document represented as URL.
${date(pattern)} - Current date. The allowed patterns are equivalent to the ones in the Java SimpleDateFormat class. Example: yyyy-MM-dd.
Note: This editor variable supports both the xs:date and xs:datetime parameters. For details about xs:date, go to: http://www.w3.org/TR/xmlschema-2/#date. For details about xs:datetime, go to: http://www.w3.org/TR/xmlschema-2/#dateTime.
${dbgXML} - The local file path to the XML document that is currently selected in the Debugger source combo box (for tools started from the XSLT/XQuery Debugger).
${dbgXSL} - The local file path to the XSL/XQuery document that is currently selected in the Debugger stylesheet combo box (for tools started from the XSLT/XQuery Debugger).
${dita.dir.url} - A special local contextual editor variable that gets expanded only in the Libraries dialog box that is accessible from the Advanced tab of DITA transformation scenarios. The Libraries dialog box allows you to specify additional libraries (JAR files or additional class paths) to be used by the transformer. This ${dita.dir.url} editor variable gets expanded to the value of the dita.dir parameter from the Parameters tab of the DITA transformation scenario.
${ds} - The path of the detected schema as a local file path for the current validated XML document.
${dsu} - The path of the detected schema as a URL for the current validated XML document.
${env(VAR_NAME)} - Value of the VAR_NAME environment variable. The environment variables are managed by the operating system. If you are looking for Java System Properties, use the ${system(var.name)} editor variable.
${framework(fr_name)} - The path (as URL) of the fr_name framework.
${framework} - The path (as URL) of the current framework directory.
${frameworkDir(fr_name)} - The path (as file path) of the fr_name framework.
Note: Since multiple frameworks might have the same name (although it is not recommended), for both ${framework(fr_name)} and ${frameworkDir(fr_name)} editor variables Oxygen XML Editor employs the following algorithm when searching for a given framework name:
- All frameworks are sorted, from high to low, according to their Priority setting from the Document Type configuration dialog box. Only frameworks that have the Enabled checkbox selected are taken into account.
- Next, if the two or more frameworks have the same name and priority, a further sorting based on the Storage setting is made, in the exact following order:
  - Frameworks stored in the internal Oxygen XML Editor options.
  - Additional frameworks added in the Locations preferences page.
  - Frameworks installed using the add-ons support.
  - Frameworks found in the main framework location (Default or Custom).
${frameworkDir} - The path (as file path) of the current framework directory.
${frameworks} - The path (as URL) of the frameworks directory. When used to define references inside a framework configuration, it expands to the parent folder of that specific framework folder. Otherwise, it expands to the main frameworks folder defined in the Document Type Association > Locations preferences page.
${frameworksDir} - The path (as file path) of the frameworks directory. When used to define references inside a framework configuration, it expands to the parent folder of that specific framework folder. Otherwise, it expands to the main frameworks folder defined in the Document Type Association > Locations preferences page.
${home} - The path (as URL) of the user home folder.
${homeDir} - The path (as file path) of the user home folder.
${i18n(key)} - Editor variable used only at framework-level to allow translating names and descriptions of Author mode actions in multiple actions. For more details, see Localizing Frameworks.
${id} - Application-level unique identifier. It is a short sequence of 10-12 letters and digits that is not guaranteed to be universally unique.
${makeRelative(base,location)} - Takes two URL-like paths as parameters and tries to return a relative path. A use-case would be to insert content references to a certain reusable component when defining code templates.
Example:
```
${makeRelative(${currentFileURL}, ${dictionaryURL}#gogu)}
```
${oxygenHome} - Oxygen XML Editor installation folder as URL.c
${oxygenInstallDir} - Oxygen XML Editor installation folder as file path.
${pd} - The file path to the folder that contains the current project file (.xpr).
${pdu} - The URL path to the folder that contains the current project file (.xpr).
${pluginDir(pluginID)} - Each plugin has an ID specified in its plugin.xml file. This editor variable expands to the file path of the folder that contains the plugin.xml file where that specific plugin ID is located.
${pluginDirURL(pluginID)} - Each plugin has an ID specified in its plugin.xml file. This editor variable expands to the URL path of the folder that contains the plugin.xml file where that specific plugin ID is located.
${pn} - Current project name.
${ps} - Path separator, which is the separator that can be used on the current platform (Windows, macOS, Linux) between library files specified in the class path.
${rootMapDir} - Will be expanded to the current root map parent directory file path.
${rootMapDirURL} - Will be expanded to the current root map parent directory URL.
${rootMapFile} - Will be expanded to the current root map file path.
${rootMapURL} - Will be expanded to the current root map URL. For example, if in the main DITA Map you define a key with a certain value:
```
  <keydef keys="test">
    <topicmeta><keywords><keyword>ABC</keyword></keywords></topicmeta>
  </keydef>
```
you can modify a DITA-OT publishing parameter to have the value: ${xpath_eval(doc('${rootMapURL}')//keydef[@keys='test']/keywords/keyword/text())}. It will be expanded to the value of that specified key name.
${selection} - The currently selected text content in the currently edited document. This variable can be used in a code template, in Author mode operations, or in a selection plugin.
${system(var.name)} - Value of the var.name Java System Property. The Java system properties can be specified in the command-line arguments of the Java runtime as -Dvar.name=var.value. If you are looking for operating system environment variables, use the ${env(VAR_NAME)} editor variable instead.
${timeStamp} - The timestamp, which is the current time in Unix format. For example, it can be used to save transformation results in multiple output files on each transformation.
${tp} - Total number of pages in the document. Used to display the total number of pages on each printed page in the Editor / Print Preferences page.
${tsf} - The transformation result file path. If the current opened file has an associated scenario that specifies a transformation output file, this variable expands to it.
${uuid} - Universally unique identifier, a unique sequence of 32 hexadecimal digits generated by the Java UUID class.
${xmlCatalogFilesList} - A list of file paths that point to all known XML catalog files, separated by semi-colons (;).
${xpath_eval(expression)} - Evaluates an XPath expression. Depending on the context, the expression can be:
- static - When executed in a non-XML context. For example, you can use such static expressions to perform string operations on other editor variables for composing the name of the output file in a transformation scenario's Output tab.
  Example:
```
${xpath_eval(upper-case(substring('${cfn}', 1, 4)))}
```
- dynamic - When executed in an XML context. For example, you can use such dynamic expression in a code template or as a value of a parameter of an Author mode operation.
  Example:
```
${ask('Set new ID attribute', generic, '${xpath_eval(@id)}')}
```