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 Author Eclipse plugin 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.
UtilAccess.expandEditorVariables(String,
URL) from plugins and framework extensions.You can use the following editor variables in Oxygen XML Author Eclipse plugin commands of external engines or other external tools, and in various places in the application, such as in transformation scenarios, and validation scenarios:
${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.
<?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><topicref keys="${xpath_eval(tokenize('${answer(@firstTopic)}', '/')[last()]
! substring-before(., '.dita'))}" href="${answer(@firstTopic)}"/>${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:
|
|
| url | Format: ${ask('message', url, 'default_value')} |
| Description: Input is considered a URL. Oxygen XML Author Eclipse plugin checks that the provided URL is valid. | |
Example:
|
|
| 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 Author Eclipse plugin 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 Author Eclipse plugin 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:
|
|
| 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:
|
|
| 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:
|
|
| 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:
|
|
| textarea | Format: ${ask('message', textarea, 'default')} |
| Description: The input is a text area that requires no special handling. | |
Example:
|
${ask('Bundle for keydefs', radio, (${xpath_eval(let $family := 'utah', $bundles := doc(environment-variable('HOME') || '/git/dita-author-tools/resource/properties/bundle-data.xml')/*/family[@name eq $family]/*, $pairs := $bundles ! concat('''',./@bundle-code, '''',':', '''',./@map-filename,'''') return string-join($pairs, ';'))}), @bundle-code)}${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.
${makeRelative(${currentFileURL}, ${dictionaryURL}#gogu)} <keydef keys="test">
<topicmeta><keywords><keyword>ABC</keyword></keywords></topicmeta>
</keydef>${xpath_eval(doc('${rootMapURL}')//keydef[@keys='test']/keywords/keyword/text())}.
It will be expanded to the value of that specified key name.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.
${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.
${ask('Set new ID attribute', generic, '${xpath_eval(@id)}')}