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 file contains information (such as name, description, and id) that is 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.

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 Developer plugin 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-FO-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 Developer plugin 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 Developer plugin renders each possible value as a radio button option.
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>

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 Developer plugin 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">
    <localName label="Name" name="element_localName" allowsAny="true" useCurrentContext="true">
        <description>The local name of the attribute's parent element.</description>           
    </localName>
    <namespace label="Namespace" name="element_namespace" allowsAny="true">
        <description>The local name of the attribute's 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">
    <localName label="Name" name="attribute_localName" useCurrentContext="true">
        <description>The name of the attribute to be converted.</description>
    </localName>
    <namespace label="Namespace" name="attribute_namespace" allowsAny="true">
        <description>The namespace of the attribute to be converted.</description>
    </namespace>        
</attributeParameter>

Note: All predefined operations are loaded from the [OXYGEN_DIR]/refactoring folder.