Custom Refactoring Operations

While Oxygen XML Editor includes a variety of predefined XML refactoring operations to help you accomplish particular tasks, you can also create custom operations according to your specific needs. For example, you could create a custom refactoring operation to convert an attribute to an element and insert the element as the first child of the parent element.

An XML Refactoring operation is defined as a pair of resources:
  • An XQuery Update script or XSLT stylesheet that Oxygen XML Editor will run to refactor the XML files.
  • An XML Operation Descriptor file that contains information about the operation (such as the name, description, and parameters).

Figure: Diagram of an XML Refactoring Operation

All the defined custom operations are loaded by the XML Refactoring Tool and presented in the Refactoring Operations wizard page, along with the predefined built-in operations.

After the user chooses an operation and specifies its parameters, Oxygen XML Editor processes an XQuery Update or XSLT transformation over the input file. This transformation is executed in a safe mode, which implies the following:
  • When loading the document:
    • The XInclude mechanism is disabled. This means that the resources included by using XInclude will not be visible in the transformation.
    • The DTD entities will be processed without being expanded.
    • The associated DTD will be not loaded, so the default attributes declared in the DTD will not be visible in the transformation.
  • When saving the updated XML document:
    • The DOCTYPE will be preserved.
    • The DTD entities will be preserved as they are in the original document when the document is saved.
    • The attribute values will be kept in their original form without being normalized.
    • The spaces between attributes are preserved. Basically, the spaces are lost by a regular XML serialization since they are not considered important.
The result of this transformation overrides the initial input file.
Note: To achieve some of the previous goals, the XML Refactoring mechanism adds several attributes that are interpreted internally. The attributes belong to the http://oxygenxml.com/app/xml_refactory/additional_attributes namespace. These attributes should not be taken into account when processing the input XML document since they are discarded when the transformed document is serialized.
Restriction: Comments or processing instructions that are in any node before or after the root element cannot be modified by an XML Refactoring operation. In other words, XML Refactoring operations can only be performed on comments or processing instructions that are inside the root element.

Creating a Custom Refactoring Operation

To create a custom refactoring operation, follow these steps:
  1. Create an XQuery Update script or XSLT file.
  2. Create an XML Refactoring Operation Descriptor file.
  3. Store both files in one of the locations that Oxygen XML Editor scans when loading the custom operations.

    Result: Once you run the XML Refactoring tool again, the custom operation appears in the Refactoring Operations wizard page.