If none of the predefined operations will help you accomplish a particular refactoring task,
you can create a custom operation that is specific to your needs. For example, if you want to
convert an attribute to an element and insert the element as the first child of the parent
element, a custom refactoring operation needs to be created.
Note: The custom refactoring
operations are only available in the Enterprise edition.
An XML Refactoring operation is defined as a pair of resources:
- An XQuery Update script file that Oxygen XML Editor will run in order to refactor the XML files.
- An XML Operation Descriptor file that contains information about the operation, such as the name, description, and parameters.
All the defined operations are loaded by the XML Refactoring tool and presented in the Refactoring operations wizard page.
After the user chooses an operation and specifies its parameters, an XQuery Update
transformation is processed 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 an 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:
- Create an XQuery Update script file.
- Create an XML Refactoring Operation Descriptor file.
- Store both files in one of the locations that Oxygen XML Editor scans when loading the custom
operations.
Once you run the XML Refactoring tool again, the custom operation appears in the Refactoring operations wizard page.