Built-in Author Mode Operations

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.

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.

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.

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. 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.

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.

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.

scenarioNames

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

scenarioNames

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

fragment

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

text

The text section to insert.

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, /frameworks/dita/commons.js) because that is the only location where Oxygen XML will look for it.

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.

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.

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.

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.

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.

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.

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.

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.

header

The text that is placed before the selection.

footer

The text that is placed after the selection.

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.

element

The element to wrap or unwrap content.

schemaAware

unwrapElementLocation

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

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.

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
        ()

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.

<article xml:lang="en">
  <ul>
     <li>B</li>
     <li>C</li>
     <li>A</li>
  </ul>
</article>

<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>

• 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.