Edit online

Built-in Author Mode Operations

This topic lists the default operations for the Author mode.

ChangeAttributeOperation

This operation allows you to add/modify/remove an attribute. You can use this operation in your own custom Author mode action to modify the value for a certain attribute on a specific XML element. The arguments of the operation are:

name
The attribute local name.
namespace
The attribute namespace.
elementLocation
The XPath location that identifies the element.
value
The new value for the attribute. If empty or null the attribute will be removed.
editAttribute
If an in-place editor exists for this attribute, it will automatically activate the in-place editor and start editing.
removeIfEmpty
The possible values are true and false. True means that the attribute should be removed if an empty value is provided. The default behavior is to remove it.

ChangeAttributesOperation

This operation allows you to add/modify/remove multiple attributes. You can use this operation in your own custom Author mode action to modify the value for one or more attributes for one or more XML elements. The arguments of the operation are:

elementLocations
The XPath location that identifies the elements whose attributes will be affected. If not defined, the element at the cursor location will be used.
attributeNames
The names of the attributes to add, modify, or remove, separated by the new-line character (\n). The values can be local names or Clark notations.
values
The new attributes values, each on a new line, separated by the new-line character (\n). An empty value will remove the attribute if removeIfEmpty is set to true.
removeIfEmpty
The possible values are true (default) and false. True means that the attribute will be removed if an empty value is provided.

ChangePseudoClassesOperation

Operation that sets a list of pseudo-class values to nodes identified by an XPath expression. It can also remove a list of values from nodes identified by an XPath expression. The operation accepts the following parameters:

setLocations
An XPath expression indicating a list of nodes that will have the specified list of pseudo-classes set. If it is not defined, then the element at the cursor position will be used.
setPseudoClassNames
A space-separated list of pseudo-class names that will be set on the matched nodes.
removeLocations
An XPath expression indicating a list of nodes that will have the specified list of pseudo-classes removed. If it is not defined, then the element at the cursor position will be used.
removePseudoClassNames
A space-separated list of pseudo-class names that will be removed from the matched nodes.
includeAllNodes
The possible values are yes and no. If set to yes, comments, CDATA, and text nodes are included when evaluating XPath expressions. If set to no, they are ignored.

DeleteElementOperation

Deletes the node indicated by the elementLocation parameter XPath expression. If missing, the operation will delete the node at the cursor location.

DeleteElementsOperation

Deletes the nodes indicated by the elementLocations parameter XPath expression. If missing, the operation will delete the node at the cursor location.

ExecuteCommandLineOperation

This operation allows you to start a process executing a given command line. It has the following arguments:

name
The name of the operation (or name of the console panel that corresponds to the process run by an action built over this operation).
workingDirectory
The path to the directory where the command line is executed. The default value is "." (current directory).
cmdLine
The command line to be executed (accepts editor variables).
showConsole
If set to true, the console panel will be displayed in Oxygen XML Author. The default value is false.
wait
If set to true, the command line will wait for the operation to finish. The default value is false.

ExecuteCustomizableTransformationScenarioOperation

Allows you to run a publishing transformation scenario configured at framework level with a specified set of parameters.
Notice: This operation is not applicable to the Oxygen XML Author Component or the Oxygen XML Web Author.

It supports the following arguments:

scenarioName

The name of the transformation scenario to execute.

scenarioParameters

Provided parameters for the transformation scenario. The parameters are inserted as name=value pairs separated by line breaks. The set parameters are taken into account for XSLT, DITA, Chemistry, and ANT transformation scenario types.

markInProgressXPathLocation

XPath expression that identifies the element(s) on which a specific -oxy-transformation-in-progress pseudo class is set before transformation is started. The pseudo class is reset when the transformation ends or is cancelled. If this XPath expression is not defined, the current node is used.

markOthersInProgressXPathLocation

XPath expression that identifies other elements on which a specific -oxy-transformation-in-progress-others pseudo class is set before the transformation is started. The pseudo class is reset when the transformation ends.

ExecuteMultipleActionsOperation

This operation allows the execution of a sequence of actions, defined as a list of action IDs. The actions must be defined by the corresponding framework, or one of the common actions for all frameworks supplied by Oxygen XML Author.

actionIDs
The action IDs list that will be executed in sequence, the list must be a string sequence containing the IDs separated by commas or new lines.

ExecuteMultipleWebappCompatibleActionsOperation

An implementation of an operation that runs a sequence of Oxygen XML Web Author-compatible actions, defined as a list of IDs.

ExecuteTransformationScenariosOperation

This operation allows running one or more transformation scenarios defined in the current document type association, in the project options, or in the global options. A use case would be to add a toolbar button that triggers publishing to various output formats. The argument of the operation is:

scenarioNames
The list of scenario names that will be executed, separated by new lines.

ExecuteValidationScenariosOperation

This operation allows running one or more validation scenarios defined in the current document type association, in the project options, or in the global options. The single argument for the operation is:

scenarioNames
The list of scenario names that will be executed, separated by new lines.

InsertEquationOperation

Inserts a fragment containing a MathML equation at the cursor offset. The argument of this operation is:

fragment
The XML fragment containing the MathML content that should be inserted.

InsertFragmentOperation

Inserts an XML fragment at the current cursor position. The selection, if there is one, remains unchanged. The fragment will be inserted in the current context of the cursor position meaning that if the current XML document uses some namespace declarations then the inserted fragment must use the same declarations. The namespace declarations of the inserted fragment will be adapted to the existing namespace declarations of the XML document. For more details about its list of parameters, see Arguments of InsertFragmentOperation.

InsertOrReplaceFragmentOperation

Similar to InsertFragmentOperation, except it removes the selected content before inserting the fragment. Also, the insertPosition parameter has another possible value: Replace. If this value is used, the operation deletes the node selected by the XPath expression denoted by the insertLocation parameter. For more details about its list of parameters, see Arguments of InsertFragmentOperation.

InsertOrReplaceTextOperation

Inserts a text at current position removing the selected content, if any. The argument of this operation is:

text
The text section to insert.

InsertXIncludeOperation

Insert an XInclude element at the cursor offset. Opens a dialog box that allows you to browse and select content to be included in your document and automatically generates the corresponding XInclude instruction.

JSOperation

Allows you to call the Java API from custom JavaScript content. For some sample JSOperation implementations, see https://github.com/oxygenxml/javascript-sample-operations.
Notice: For the Oxygen XML Web Author, this operation cannot be invoked using the JavaScript API. However, it can be used when configuring an Action for Author mode using the Document Type Configuration dialog box.

This operation accepts the following parameter:

script

The JavaScript content to execute. It must have a function called doOperation(), which can use the predefined authorAccess variable. The authorAccess variable has access to the entire ro.sync.ecss.extensions.api.AuthorAccess Java API.

The following example is a script that retrieves the current value of the type attribute on the current element, allows the end-user to edit its new value and sets the new value in the document:
function doOperation(){ 
 //The current node is either entirely selected...
 currentNode = authorAccess.getEditorAccess().getFullySelectedNode();
 if(currentNode == null){
 //or the cursor is placed in it
 caretOffset = authorAccess.getEditorAccess().getCaretOffset(); 
 currentNode = authorAccess.getDocumentController().getNodeAtOffset
                          (caretOffset);
 }
 //Get current value of the @type attribute
  currentTypeValue = "";
  currentTypeValueAttr = currentNode.getAttribute("type");
  if(currentTypeValueAttr != null){
    currentTypeValue = currentTypeValueAttr.getValue();
  }
 //Ask user for new value for attribute.
 newTypeValue = javax.swing.JOptionPane.showInputDialog
                         ("Input @type value", currentTypeValue);
 if(newTypeValue != null){
   //Create and set the new attribute value for the @type attribute.
   attrValue = new Packages.ro.sync.ecss.extensions.api.node.AttrValue
                         (newTypeValue);
   authorAccess.getDocumentController().setAttribute
                         ("type", attrValue, currentNode);
 }
} 
Tip: You can call functions defined inside a script called commons.js from your custom script content so that you can use that external script file as a library of functions. Note that this commons.js file must be placed in the root of the framework directory (for example, [OXYGEN_INSTALL_DIR]/frameworks/dita/commons.js) because that is the only location where Oxygen XML Author will look for it.

MoveCaretOperation

Flexible operation for moving the cursor within a document and it is also capable of performing a selection. The operation accepts the following arguments:

xpathLocation
An XPath expression that identifies the node relative to where the cursor will be moved. If the expression identifies more than one node, only the first one will be taken into account.
position
The position relative to the node obtained from the XPath expression where the cursor will be moved. When also choosing to perform a selection, you can use the following possible values:
  • Before - Places the cursor at the beginning of the selection.
  • Inside, at the beginning - Places the cursor at the beginning of the selection.
  • After - Places the cursor at the end of the selection.
  • Inside, at the end - Places the cursor at the end of the selection.
selection
Specifies if the operation should select the element obtained from the XPath expression, its content, or nothing at all. The possible values of the argument are: None, Element, and Content.

MoveElementOperation

Flexible operation for moving an XML element to another location from the same document. XPath expressions are used to identify the source element and the target location. The operation takes the following parameters:

sourceLocation
XPath expression that identifies the content to be moved.
deleteLocation
XPath expression that identifies the node to be removed. This parameter is optional. If missing, the sourceLocation parameter will also identify the node to be deleted.
surroundFragment
A string representation of an XML fragment. The moved node will be wrapped in this string before moving it in the destination.
targetLocation
XPath expression that identifies the location where the node must be moved to.
insertPosition
Argument that indicates the insert position.
moveOnlySourceContentNodes
When set to true, only the content of the source element is moved.
processTrackedChangesForXpathLocations
When nodes are located via an XPath expression and the nodes are deleted with Change Tracking enabled, they are considered as being present by default (thus, the change tracking is ignored). If you set this argument to true and change tracking is enabled, deleted nodes will be ignored when the XPath locations are computed (thus, the change tracking is NOT ignored).
alwaysPreserveTrackedChangesInMovedContent
When set to true, tracked changes are included when a copied fragment is inserted in a document, regardless of the current state of the Track Changes feature.

OpenInSystemAppOperation

Opens a resource in the system application that is associated with the resource in the operating system. The arguments of this operation are:

resourcePath
An XPath expression that, when executed, returns the path of the resource to be opened. Editor variables are expanded in the value of this parameter, before the expression is executed.
isUnparsedEntity
Possible values are true or false. If the value is true, the value of the resourcePath argument is treated as the name of an unparsed entity.

ReloadContentOperation

Reloads the content of the editor by re-reading the information from the URL used to open it. It accepts the following argument:

markAsNotModified
The possible values are true and false. After reloading the editor, the content may appear as modified and in some cases where the content is already present on the file server, you would not want the user to save it again. You can set this flag to true to prevent the editor from showing the content as modified.

RemovePseudoClassOperation

An operation that removes a pseudo-class from an element. Accepts the following parameters:

name
Name of the pseudo-class to be removed.
includeAllNodes
The possible values are yes and no. If set to yes, comments, CDATA, and text nodes are included when evaluating XPath expressions. If set to no, they are ignored.
elementLocation

The XPath location that identifies the element. If it is not defined, then the element at the cursor position is used. It can also identify multiple elements, in which case the pseudo class will be removed from all of them.

Example:

Suppose that there is a pseudo-class called myClass on the element paragraph and there are CSS styles matching the pseudo-class.
paragraph:myClass{
  font-size:2em;
  color:red;
}
paragraph{
  color:blue;
}

In the previous example, by removing the pseudo-class, the layout of the paragraph is rebuilt by matching the other rules (in this case, the foreground color of the paragraph element will become blue.

RenameElementOperation

This operation allows you to rename all occurrences of the elements identified by an XPath expression. The operation requires two parameters:

elementName
The new element name.
elementLocation
The XPath expression that identifies the element occurrences to be renamed. If this parameter is missing, the operation renames the element at current cursor position.

ReplaceElementContentOperation

An operation that replaces the content of the element at the cursor location (or fully selected element). The operation accepts the following parameters:

fragment
Specifies the fragment that will be inserted as the element content.
elementLocation
An XPath expression that identifies the element. If it is not defined, then the element at the cursor position is used.

SetPseudoClassOperation

An operation that sets a pseudo-class to an element. The operation accepts the following parameters:

elementLocation
An XPath expression that identifies the element that will have the pseudo-class set. If it is not defined, then the element at the cursor position is used.
name
The pseudo-class local name.
includeAllNodes
The possible values are yes and no. If set to yes, comments, CDATA, and text nodes are included when evaluating XPath expressions. If set to no, they are ignored.

ShowElementDocumentationOperation

Opens the associated specification HTML page for the current element. The operation accepts as parameter a URL pattern that points to the HTML page containing the documentation.

StopCurrentTransformationScenarioOperation

Allows you to stop the transformation scenario that is currently running.
Notice: This operation is not applicable to the Oxygen XML Author Component or the Oxygen XML Web Author.

SurroundWithFragmentOperation

Surrounds the selected content with a text fragment. Since the fragment can have multiple nodes, the surrounded content will be always placed in the first leaf element. If there is no selection, the operation will simply insert the fragment at the cursor position. For more details about the list of parameters go to: Arguments of SurroundWithFragmentOperation.

SurroundWithTextOperation

This operation has two arguments (two text values) that will be inserted before and after the selected content. If there is no selected content, the two sections will be inserted at the cursor position. The arguments of the operation are:

header
The text that is placed before the selection.
footer
The text that is placed after the selection.

TogglePseudoClassOperation

An implementation of an operation to toggle on/off the pseudo-class of an element. Accepts the following parameters:

name
Name of the pseudo-class to be toggled on/off.
includeAllNodes
The possible values are yes and no. If set to yes, comments, CDATA, and text nodes are included when evaluating XPath expressions. If set to no, they are ignored.
elementLocation

The XPath location that identifies one or more elements that will have the pseudo class toggled. If it is not defined, then the element at the cursor position is used.

Example:
paragraph:myClass{
  color:red;
}
paragraph{
  color:blue;
}

By default, the paragraph content is rendered in blue. Suppose that you have a TogglePseudoClassOperation configured for the myClass pseudo-class. Invoking it the first time will set the myClass pseudo-class and the paragraph will be rendered in red. Invoking the operation again, will remove the pseudo-class and the visible result will be a blue rendered paragraph element.

ToggleSurroundWithElementOperation

This operation allows wrapping and unwrapping content in a specific wrapper element that can have certain attributes specified on it. It is useful to implement toggle actions such as highlighting text as bold, italic, or underline. The operation supports processing multiple selection intervals, such as multiple cells within a table column selection. The arguments of the operation are:

element
The element to wrap or unwrap content.
schemaAware
This argument applies only on the surround with element operation and controls whether or not the insertion is valid, based upon the schema. If the insertion is not valid, then wrapping action will be broken up into smaller intervals until the wrapping action is valid. For example, if you try to wrap a paragraph element with a bold element, it would not be valid, so the operation will wrap the text inside the paragraph instead, since it would be valid at that position.

ToggleCommentOperation

This operation allows for commenting or un-commenting the selected content. It does not have any arguments. If the selection is text, the operation wraps the selection in a comment. If the selection is a comment, the operation removes the comment.

UnwrapTagsOperation

This operation allows removing the element tags either from the current element or for an element identified with an XPath location. The argument of the operation is:

unwrapElementLocation
An XPath expression that identifies the element to unwrap. If it is not defined, the element at the cursor position is unwrapped.

XQueryUpdateOperation

Allows you to execute an XQuery Update script directly over content in Author mode.
Notice: This operation is not applicable to the Oxygen XML Author Component or the Oxygen XML Web Author.

It supports the following arguments:

script

The XQuery Update script to be executed. The value can either be an XQuery script or a URL that points to the XQuery Update script. You can use the ${framework} or ${frameworkDir} editor variables to refer the scripts from the framework directory.

The script will be executed in the context of the node at the cursor position. If the script declares the following variable, it will also receive the selected nodes (assuming that entire nodes are selected):
declare variable $oxyxq:selection external;

In the example below, you can see how this argument is used.

externalParams

A string that can assign multiple key-value pairs separated by a comma or a new line character.

For example, if an XQuery script declares two external parameters like this:
declare variable $param1 external;
declare variable $param2 external;

You can pass custom values for each parameter by setting the externalParams to param1=value1,param2=value2.

expandXincludeReferences
Makes all Xinclude elements transparent to the XQuery transformer. When the Xinclude references are transparent, the XQueryUpdateOperation can use the referenced elements for further processing in the current document, but it cannot change their values in the original document. The default value is false, which means the Xinclude elements are not transparent.
An example of an XQuery Update Script that converts paragraphs to list items:
declare namespace oxyxq = "http://www.oxygenxml.com/ns/xqu";
(: This variable will be linked to the selected nodes assuming that there are 
actually fully selected nodes. For example this selection will return null: 
<p>{SEL_START}text{SEL_END} in para</p>
but this will give two "p" elements:
{SEL_END}<p>text</p><p>text2</p>{SEL_END}

If a multiple selection exists it will also be processed and forwarded.
 Again, only fully selected nodes will be passed.
:)
declare variable $oxyxq:selection external;

(: We will process either the selection or the context node :)
let $toProcess := if (empty($oxyxq:selection)) then
    (.)
else
    ($oxyxq:selection)

return if (not(empty($toProcess))) then
        (
        (: Create the list :)
        let $ul :=
        <ul>
            {
                for $sel in $toProcess
                return
                    <li>{$sel}</li>
            }
        </ul>
        
        return
            (
            (: Delete the processed nodes :)
            for $sel in $toProcess
            return
                delete node $sel,
            (: Inserts the constructed list :)
            insert node $ul
                before $toProcess[1]
            )
        )
    else
        ()

XSLTOperation and XQueryOperation

Applies an XSLT or XQuery script on a source element and then replaces or inserts the result in a specified target element.
Notice: For Oxygen XML Web Author, these operations cannot be invoked using the JavaScript API.

These operations accept the following parameters:

sourceLocation

An XPath expression indicating the element that the script will be applied on. If it is not defined, then the element at the cursor position will be used.

There may be situations where you want to look at an ancestor of the current element and make decisions in the script based on that. To do this, you can set the sourceLocation to point to an ancestor node then use the oxy:current-element() function to access the current element, as in the following example:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0" 
  xpath-default-namespace="http://docbook.org/ns/docbook" 
  xmlns:oxy="http://www.oxygenxml.com/ns/author/xpath-extension-functions" 
                           exclude-result-prefixes="oxy">     
    <xsl:template match="/">
        <xsl:apply-templates select="oxy:current-element()"/>
    </xsl:template>
    
    <xsl:template match="para">
        <!-- And the context is again inside the current element, 
        but we can use information from the entire XML -->
        <xsl:variable 
            name="keyImage" select="//imagedata[@fileref='images/lake.jpeg']
              /ancestor::inlinemediaobject/@xml:id/string()"/>
        <xref linkend="{$keyImage}" role="key_include" 
                  xmlns="http://docbook.org/ns/docbook"/>
    </xsl:template>    
</xsl:stylesheet>
targetLocation
An XPath expression indicating the insert location for the result of the transformation. If it is not defined then the insert location will be at the cursor location.
script

The script content (XSLT or XQuery). The base system ID for this will be the framework file, so any include/import reference will be resolved relative to the .framework file that contains this action definition.

For example, for the following script, the imported xslt_operation.xsl needs to be located in the current framework directory.
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
             version="1.0">
    <xsl:import href="xslt_operation.xsl"/>
</xsl:stylesheet>
You can also use a path for an included or imported reference. When using a path, the following apply:
  • A relative path is resolved to the framework directory.
  • The ${framework} editor variable can also be used to reference resources from the framework directory.
  • The path is passed through the catalog mappings. It helps to use an absolute URL (for instance, http://www.oxygenxml.com/fr/testy.xsl) and map it in the catalog.xml file from the framework directory to a resource from the framework.
action
The insert action relative to the node determined by the target XPath expression. It can be: Replace, At cursor position, Before, After, Inside as first child or Inside as last child.
caretPosition
The position of the cursor after the action is executed. It can be: Preserve, Before, Start, First editable position, End, or After. If this parameter is not set, you can still indicate the position of the cursor by using the ${caret} editor variable in the inserted content.
expandEditorVariables
Parameter controlling the expansion of editor variables returned by the script processing. Expansion is enabled by default.
suspendTrackChanges
It has 2 possible values (true and false). The default value is false. When set to true, the Track Changes feature is deactivated. When using this argument, after the action is finished, the state of the Track Changes feature is restored to its initial value.
externalParams

A string that can assign multiple key-value pairs separated by a comma or a new line character.

For example, if an XQuery script declares two external parameters like this:
declare variable $param1 external;
declare variable $param2 external;

You can pass custom values for each parameter by setting the externalParams to param1=value1,param2=value2.

escapeEntityRefs
Escapes entity references in processed content to plain text and unescapes them back in the returned content.

XSLTOperation Example: Sort a list with respect to the language declared on the root element:

Suppose you want an action that will sort a list with respect to the language declared on the root element and you have an XML file like this:
<article xml:lang="en">
  <ul>
     <li>B</li>
     <li>C</li>
     <li>A</li>
  </ul>
</article>

The XSLTOperation needs to be configured as follows:

  • sourceLocation is set to /* so that the script has access to the root element and its children.
  • targetLocation is left untouched (assuming that the action is active only when the cursor is inside the list).
The XSLT script would look like this:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:oxy="http://www.oxygenxml.com/ns/author/xpath-extension-functions" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  exclude-result-prefixes="xs oxy" version="2.0">

  <xsl:template match="/">
      <!-- 
          sourceLocation parameter was set to /* to have a larger context.
          We can pinpoint the element that contained the caret 
          using the oxy:current-element() function.
      -->
      <xsl:apply-templates select="oxy:current-element()"/>
  </xsl:template>

  <xsl:template match="ul">
        
    <!-- Because the sourceLocation parameter was set to /* we now have access to 
         the root element and its attributes. -->
    <xsl:variable name="lang" select="/*/@xml:lang"/>
    <xsl:variable name="collationURI">
      <xsl:value-of select="concat('http://www.w3.org/2013/collation/UCA?lang=', $lang)"/>
    </xsl:variable>
        
      <xsl:copy>
          <xsl:copy-of select="@*"/>
            
          <!-- Copy the list items, but sorted. -->
          <xsl:apply-templates select="li">
              <xsl:sort collation="{$collationURI}" select="text()"/>
          </xsl:apply-templates>
      </xsl:copy>
  </xsl:template>
    
  <!-- This copy template will handle the contents of the list items. -->
  <xsl:template match="@* | node()">
      <xsl:copy>
          <xsl:apply-templates select="@* | node()"/>
      </xsl:copy>
  </xsl:template>
</xsl:stylesheet>
Using Entities and Xincludes with the XSLTOperation
  • Entities are treated as plain text and not expanded.
  • Xincludes are resolved in the result, and you can alter the XML obtained afterward using the XSLT/XQuery script of the operation, but you cannot alter the included document itself.

Editor Variables in Author Mode Operations

Author mode operations can include parameters that contain the following editor variables:
  • ${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.
  • ${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.
  • ${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 Author 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 Author 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 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')}
  • ${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.
  • ${uuid} - Universally unique identifier, a unique sequence of 32 hexadecimal digits generated by the Java UUID class.
  • ${id} - Application-level unique identifier. It is a short sequence of 10-12 letters and digits that is not guaranteed to be universally unique.
  • ${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.
  • ${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.
  • ${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.
  • ${pd} - The file path to the folder that contains the current project file (.xpr).
  • ${oxygenInstallDir} - Oxygen XML Author installation folder as file path.
  • ${homeDir} - The path (as file path) of the user home folder.
  • ${pn} - Current project name.
  • ${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.
  • ${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.
  • ${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.
Edit online

How to Find More Information About the Arguments of an Operation

If you need to find more information about the arguments of an operation, there are several places where this information is available:
  • In the API documentation for the particular operation.
  • By invoking the getArguments() method on the operation.
  • In the source code of the operation.
  • In Oxygen XML Author:
    1. Go to Options > Preferences > Document Type Association, select a document type and click the New, Edit, Duplicate, or Extend button.
    2. Go to the Author tab and then the Actions subtab. At the bottom of this subtab, click New to open the Action dialog box.
    3. Locate the Operation field and click the Choose button on the right side. This will open a dialog box that displays the default operations.
    4. Double-click the operation (or select it and click OK).

      The arguments for the operation will now be displayed in the Action dialog box.