Edit online

Custom Refactoring Operation Descriptor File

The second step in creating a custom refactoring operation is to create an operation descriptor file. The easiest way to do this is to use the New document wizard and choose the XML Refactoring Operation Descriptor template.

Introduction to the Descriptor File

This descriptor file root element specifies required attributes to define the operation @name, @description, and @id which are necessarily when loading an XML Refactoring operation. It also contains the path to the XQuery Update script or XSLT stylesheet that is associated with the particular operation through the <script> element.

The optional @filesFilter attribute can be specified to filter the resources by using a file pattern or list of file patterns separated by a comma (for example: filesFilter="*.dita, *.xml"). When set, its value is automatically populated in the Include files field within the Scope and Filters wizard page as a default value.

You can specify a category for your custom operations to logically group certain operations. The <category> element is optional and if it is not included in the descriptor file, the default name of the category for the custom operations is Other operations.

The descriptor file is edited and validated against the following schema: frameworks/xml_refactoring/operation_descriptor.xsd.

Declaring Parameters in the Descriptor File

If the XQuery Update script or XSLT stylesheet includes parameters, they should be declared in the parameters section of the descriptor file. All the parameters specified in this section of the descriptor file will be displayed in the XML Refactoring tool within the Configure Operation Parameters wizard page for that particular operation.

The value of the first <description> element in the <parameters> section will be displayed at the top of the Configure Operation Parameters wizard page.

To declare a parameter, specify the following information:

label - This value is displayed in the user interface for the parameter.
name - The parameter name used in the XQuery Update script or XSLT stylesheet and it should be the same as the one declared in the script.
type - Defines the type of the parameter and how it will be rendered. There are several types available:
- TEXT - Generic type used to specify a simple text fragment.
- XPATH - Type of parameter whose value is an XPATH expression. For this type of parameter, Oxygen XML Editor will use a text input with corresponding content completion and syntax highlighting.
  Note: The value of this parameter is transferred as plain text to the XQuery Update or XSLT transformation without being evaluated. You should evaluate the XPath expression inside the XQuery Update script or XSLT stylesheet. For example, you could use the saxon:evaluate Saxon extension function.
  Note: A relative XPath expression is converted to an absolute XPath expression by adding // before it (//XPathExp). This conversion is done before transferring the XPath expression to the XML refactoring engine.
  Note: When writing XPath expressions, you can only use prefixes declared in the Options > Preferences > XML > XSLT-XQuery > XPath options page.
- NAMESPACE - Used for editing namespace values.
- REG_EXP_FIND - Used when you want to match a certain text by using Perl-like regular expressions.
- REG_EXP_REPLACE - Used along with REG_EXP_FIND to specify the replacement string.
- XML_FRAGMENT - This type is used when you want to specify an XML fragment. For this type, Oxygen XML Editor will display a text area specialized for inserting XML documents.
- NC_NAME - The parameter for NC_NAME values. It is useful when you want to specify the local part of a QName for an element or attribute.
- BOOLEAN - Used to edit boolean parameters.
- TEXT_CHOICE - It is useful for parameters whose value should be from a list of possible values. Oxygen XML Editor renders each possible value as a radio button option.
optional - Specifies whether the parameter is optional or required. For optional parameters, the end user is not required to fill in a value in the XML refactoring wizard.
description - The description of the parameter. It is used by the application to display a tooltip when you hover over the parameter.
possibleValues - Contains the list with possible values for the parameter and you can specify the default value, as in the following example:
```
<possibleValues onlyPossibleValuesAllowed="true">
    <value name="before">Before</value>
    <value name="after" default="true">After</value>
    <value name="firstChild">First child</value>
    <value name="lastChild">Last child</value>
</possibleValues>
```
On a <value>, you can specify the @default attribute with the value true to mark it as the default presented value in the XML refactoring wizard. The text specified inside the <value> element is displayed as placeholder default text in the text entry box. If the dialog box is accepted with the placeholder text in place, the @name attribute value is passed to the refactoring script. Example:
```
<value name="my-actual-default-value" default="true">[default displayed]</value> 
```

Specialized Parameters to Match Elements or Attributes

If you want to match elements or attributes, you can use some specialized parameters, in which case Oxygen XML Editor will propose all declared elements or attributes based on the schema associated with the currently edited file. The following specialized parameters are supported:

elementLocation

This parameter is used to match elements. For this type of parameter, the application displays a text field where you can enter the element name or an XPath expression. The text from the @label attribute is displayed in the application as the label of the text field. The @name attribute is used to specify the name of the parameter from the XQuery Update script or XSLT stylesheet. If the value of the @useCurrentContext attribute is set to true, the element name from the cursor position is used as proposed values for this parameter.

Example of an <elementLocation>:

<elementLocation name="elem_loc" useCurrentContext="false">
                <element label="Element location">
                    <description>Element location description.</description>
                </element>
</elementLocation>

attributeLocation

This parameter is used to match attributes. For this type of parameter, the application displays two text fields where you can enter the parent element name and the attribute name (both text fields accept XPath expressions for a finer match). The text from the @label attributes is displayed in the application as the label of the associated text fields. The @name attribute is used to specify the name of the parameter from the XQuery Update script or XSLT stylesheet. The value of this parameter is an XPath expression that is computed by using the values of the expression from the element and attribute text fields. For example, if section is entered for the element and a title is entered for the attribute, the XPath expression would be computed as //section/@title. If the value of the useCurrentContext attribute is set to true, the element and attribute name from the cursor position is used as proposed values for the operation parameters.

Example of an <attributeLocation>:

<attributeLocation name="attr_xpath" useCurrentContext="true">
                <element label="Element path">
                    <description>Element path description.</description>
                </element>
                <attribute label="Attribute" >
                    <description>Attribute path description.</description>
                </attribute>
</attributeLocation>

elementParameter

This parameter is used to specify elements by local name and namespace. For this type of parameter, the application displays two combo boxes with elements and namespaces collected from the associated schema of the currently edited file. The text from the @label attribute is displayed in the application as label of the associated combo. The @name attribute is used to specify the name of the parameter from the XQuery Update script or XSLT stylesheet. If you specify the @allowsAny attribute, the application will propose <ANY> as a possible value for the Name and Namespace combo boxes. You can also use the @useCurrentContext attribute and if its value is set to true, the element name and namespace from the cursor position is used as proposed values for the operation parameters.

Example of an <elementParameter>:

<elementParameter id="elemID" useCurrentContext="true">
    <localName label="Name" name="element_localName" allowsAny="true">
        <description>Local name of the parent element.</description>           
    </localName>
    <namespace label="Namespace" name="element_namespace" allowsAny="true">
        <description>Local name of the parent element</description>           
    </namespace>        
</elementParameter>

attributeParameter

This parameter is used to specify attributes by local name and namespace. For this type of parameter, the application displays two combo boxes with attributes and their namespaces collected from the associated schema of the currently edited file. The text from the @label attribute is displayed in the application as the label of the associated combo box. You can also use the @useCurrentContext attribute and if its value is set to true, the attribute name and namespace from the cursor position is used as proposed values for the operation parameters.

Note: An <attributeParameter> is dependant upon an <elementParameter>. The list of attributes and namespaces are computed based on the selection in the elementParameter combo boxes.

Example of an <attributeParameter>:

<attributeParameter dependsOn="elemID" useCurrentContext="true">
    <localName label="Name" name="attribute_localName">
        <description>The name of the attribute to be converted.</description>
    </localName>
    <namespace label="Namespace" name="attribute_namespace" allowsAny="true">
        <description>Namespace of the attribute to be converted.</description>
    </namespace>        
</attributeParameter>

Grouping Parameters in the Descriptor File

You can use <section> elements to group related parameters in the descriptor file:

<section label="Parent element">
  <elementParameter id="elemID">
    <localName label="Name" name="element_localName" allowsAny="true">
      <description>Local name of the parent element.</description>            
    </localName>
    <namespace label="Namespace" name="element_namespace" allowsAny="true">
      <description>Local name of the parent element</description>            
    </namespace>        
  </elementParameter>
</section>

Note: All built-in operations are loaded from the [OXYGEN_INSTALL_DIR]/refactoring folder.