Custom Refactoring Operation Descriptor File

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 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 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 and it should be the same as the one declared in the XQuery 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 transformation without being evaluated. To evaluate it in the XQuery Update script 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 XQuery Update 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 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.
• 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 (elementParameter and attributeParameter)

If you want to match elements or attributes, use the specialized parameters elementParameter or attributeParameter. If you use these parameters, Oxygen XML Editor will propose all declared elements or attributes based on the schema associated with the currently edited file.

Example of an elementParameter:

<elementParameter id="elemID">
    <localName label="Name" name="element_localName" allowsAny="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>

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. If you specify the allowsAny attribute, the application will propose <ANY> as a possible value for the Name and Namespace combo boxes.

Example of an attributeParameter:

<attributeParameter dependsOn="elemID">
    <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>The namespace of the attribute to be converted.</description>
    </namespace>        
</attributeParameter>