Author Mode Default Operations

The default operations for the Author mode, along with their arguments are as follows:

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 inserted fragment will not be copied and pasted to the cursor position, but the namespace declarations of the fragment will be adapted if needed to the existing namespace declarations of the XML document. For more details about the list of parameters go to The arguments of InsertFragmentOperation operation.
InsertOrReplaceFragmentOperation
Similar to InsertFragmentOperation, except it removes the selected content before inserting the fragment.
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.
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 caret position. For more details about the list of parameters go to The 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 caret 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.
InsertEquationOperation
Inserts a fragment containing a MathML equation at caret offset. The argument of this operation is:
- fragment - The XML fragment containing the MathML content which should be inserted.
OpenInSystemAppOperation
Opens a resource in the system application that is associated with the resource in the operating system. The arguments of this operation is:
- 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.
InsertXIncludeOperation
Insert an XInclude element at caret offset.
ChangeAttributeOperation
This operation allows adding/modifying/removing an attribute. You can use this operation in your own Author 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.
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 indicating the element to unwrap. If it is not defined, the element at caret is unwrapped.
ToggleSurroundWithElementOperation
This operation allows wrapping and unwrapping content in a specific wrapper element which 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.
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 caret position.
ExecuteTransformationScenariosOperation
This operation allows running one or more transformation scenarios defined in the current document type association. It is useful to add to the toolbar buttons that trigger 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.
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.
This operation has 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 caret position will be used.
  There may be situations in which you want to look at an ancestor of the current element and take decisions in the script based on this. In order to do this you can set the sourceLocation to point to an ancestor node (for example /) then declare a parameter called currentElementLocation in your script and use it to re-position in the current element like:
```
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0" 
  xpath-default-namespace="http://docbook.org/ns/docbook" 
  xmlns:saxon="http://saxon.sf.net/" exclude-result-prefixes="saxon">     
    
    <xsl:param name="currentElementLocation"/>
    
    <xsl:template match="/">
        
        <xsl:apply-templates 
        select="saxon:eval(saxon:expression($currentElementLocation))"/>
    </xsl:template>
    
    <xsl:template match="para">
        
        <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:value-of 
                          select="$currentElementLocation"></xsl:value-of>
        </xref>
    </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 caret.
- 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's directory.
```
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
             version="1.0">
    <xsl:import href="xslt_operation.xsl"/>
</xsl:stylesheet>
```
- action
  The insert action relative to the node determined by the target XPath expression. It can be: Replace, At caret position, Before, After, Inside as first child or Inside as last child.
- caretPosition
  The position of the caret after the action is executed. It can be: Preserve, Before, Start, First editable position, End or After. If not specified the caret position ca be specified by outputting in the XSLT script a ${caret} editor variable.
- expandEditorVariables
  Parameter controlling the expansion of editor variables returned by the script processing. Expansion is enabled by default.
JSOperation
Allows you to call the Java API from custom JavaScript content.
This operation has the following parameters:
- 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 can be used to move the caret location after the current element:
```
function doOperation(){ 
caretOffset = authorAccess.getEditorAccess().getCaretOffset(); 
currentNode = authorAccess.getDocumentController().getNodeAtOffset(caretOffset); 
//Move caret after current node 
authorAccess.getEditorAccess().setCaretPosition(currentNode.getEndOffset() + 1); 
} 
```
Note: If you have a script called commons.js in the framework directory, you can call functions defined inside it from your custom script content so that you can use that external script file as a library of functions.
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 which will be executed in sequence, the list must be a string sequence containing the IDs separated by new lines.
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 true, only the content of the source element is moved.
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 on which the specified list of pseudo classes will be set. If it is not defined, then the element at the caret position will be used.
- setPseudoClassNames - A space-separated list of pseudo class names which will be set on the matched nodes.
- removeLocations - An XPath expression indicating a list of nodes from which the specified list of pseudo classes will be removed. If it is not defined, then the element at the caret position will be used.
- removePseudoClassNames - A space-separated list of pseudo class names which will be removed from the matched nodes.
SetPseudoClassOperation
An operation that sets a pseudo-class to an element. The operation accepts the following parameters:
- elementLocation - An XPath expression indicating the element on which the pseudo-class will be set. If it is not defined, then the element at caret position will be used.
- name - The pseudo-class local name.

Author operations can include parameters that contain the following editor variables:

${caret} - The position where the caret is inserted. This variable can be used in a code template, in Author operations, or in a selection plugin.
${selection} - The current selected text content in the current edited document. This variable can be used in a code template, in Author operations, or in a selection plugin.

${ask('message', type, ('real_value1':'rendered_value1'; 'real_value2':'rendered_value2'; ...), 'default_value')} - 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.

type - Optional parameter, with one of the following values:

Parameter
`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`.
`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.
`generic`	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!'`.
`relative_url`	Format: `${ask('message', relative_url, 'default')}`
	Description: Input is considered a URL. 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 current edited document location.
`combobox`	Format: `${ask('message', combobox, ('real_value1':'rendered_value1';...;'real_valueN':'rendered_valueN'), 'default')}`
	Description: Displays a dialog box that offers a drop-down list. The drop-down list is populated with the given `rendered_value` values. Choosing such a value will return its associated value (`real_value`).
	Example: `${ask('Operating System', combobox, ('win':'Microsoft Windows';'osx':'Mac OS X';'lnx':'Linux/UNIX'), 'osx')}` - The dialog box has the name `'Operating System'`. The drop-down list displays the three given operating systems. The associated value will be returned based upon your selection. Note: In this example `Mac OS X` is the default selected value and if selected it would return `osx` for the output.
`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 list with editable elements. The drop-down list 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.
	Example: `${ask('Operating System', editable_combobox, ('win':'Microsoft Windows';'osx':'Mac OS X';'lnx':'Linux/UNIX'), 'osx')}` - The dialog box has the name `'Operating System'`. The drop-down list 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.
`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`.
	Example: `${ask('Operating System', radio, ('win':'Microsoft Windows';'osx':'Mac OS X';'lnx':'Linux/UNIX'), 'osx')}` - 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 `Mac OS X` is the default selected value and if selected it would return `osx` for the output.

'default-value' - optional parameter. Provides a default value.

${timeStamp} - Time stamp, that is the current time in Unix format. It can be used for example to save transformation results in different output files on each transform.
${uuid} - Universally unique identifier, a unique sequence of 32 hexadecimal digits generated by the Java UUID class.
${id} - Application-level unique identifier; a short sequence of 10-12 letters and digits which is not guaranteed to be universally unique.
${cfn} - Current file name without extension and without parent folder. The current file is the one currently opened and selected.
${cfne} - Current file name with extension. The current file is the one currently opened and selected.
${cf} - Current file as file path, that is the absolute file path of the current edited document.
${cfd} - Current file folder as file path, that is the path of the current edited document up to the name of the parent folder.
${frameworksDir} - The path (as file path) of the [OXYGEN_DIR]/frameworksdirectory.
${pd} - Current project folder as file path. Usually the current folder selected in the Project View.
${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.