Developers

Omnis Technical Note TNXM0001

Creating XML documents with oXML

For Omnis Studio 4 or above
By Jason Gissing

Note the oXML component is included in Omnis Studio in Studio 6 or above. For older versions, you need to purchase a full license for full deployment mode.

The oXML external component makes the handling of XML documents simple within an Omnis application. It treats each node as a separate object, enabling easy searching and manipulation of these nodes within the document. To create an XML document you need to create an Omnis Object with the subtype DOM document object and add different elements to the object. You can do this using the methods built into the document object.

Creating an XML Document

To create an XML document, first you must create a DOM document object (external objects -> DOM document). This is the master object of your document, and allows you to create, search, edit and delete all types of nodes within your document.

Adding an Element

Your XML document will be made up of several "elements". Each element must have a name, but may also have several other properties associated with it, such as attributes, text, and comments. These will be discussed later.

Each element may also contain other elements (known as its children), thereby creating the tree type structure associated with the XML document.

Elements (and all other objects) are created by the DOM document object using its $createXXX() methods. For example, the following method returns an element object, oRoot, named "Root":

; Define oXML as Object, with subtype DOM document object
; Define lError as Character
; Define oRoot as Object, with subtype DOM Element object
; Define oObj as Object, no subtype
Do oXML.$createelement("Root",lError) returns oRoot

Once you have created an element object, you must insert it into the document. This must be done from the element object that will become the parent of the element you are about to add. The element object has two methods for this:

• $appendchild() inserts the element at the end of its list of children.
• $insertbefore() inserts the element before the stated object.

As there are no elements when you create your first element, you must use the DOM document object as its parent: this creates what is known as the "Root" element, of which there can only be one, and all other elements are descendants of this.

Do oXML.$appendchild(oRoot ,lError)
Do oXML.$createelement("Element1",lError) returns oObj
Do oRoot.$appendchild(oObj, lError)

The above method inserts the Root element into the document, then creates another element (Element1), which it returns in oObj (since oObj has no subtype, its type is defined when it has an object assigned to it; this keeps the number of variables down). The element is then inserted as a child of oRoot.

Properties of Elements

Although you have now added some elements, they contain no information. An element may have various properties associated with it. These are all added as children of the element, in the same way that elements are added as children of their parent elements. These may be added before or after inserting the element.

Adding Text

There are two possible ways of displaying text, parsed and unparsed. The usual method is parsed, which means your XML parser will evaluate the text. For example, "Apples & Pears" will be equated to "Apples & Pears". Using unparsed will not evaluate the text and so will express it literally, in this case, "Apples & Pears".

; to create PARSED text
Do oXML.$createtextnode("Apples & Pears", lError) returns oObj
; to create UNPARSED text
Do oXML.$createcdatasection("Apples & Pears", lError) returns oObj

Will create a text node containing the text, then to add it to the element oElement:

Do oElement.$appendchild(oObj, lError)

Adding Attributes

Attributes are added in a very simple manner. They require just a name and a value, and are added to the element with its $setattribute() method, as follows:

Do oElement.$setattribute('Colour','red',lError)

This will add the attribute Colour = "red" to the element oElement. You can use this method many times to add multiple attributes to the same element. Attributes can also be added using the usual method, such as oXML.$createattribute(), then the attribute is added as a child of element.

Adding Comments

Comments are not processed by XML parsers, but are present only to improve readability of the XML document. They follow the general form:

Do oXML.$createcomment('Your comment here', lError) Returns oObj
Do oElement.$appendchild(oObj, lError)

Processing Instructions

Processing instructions are used in XML as a way to keep processor-specific information in the text of the document. They store a target and a value to pass that target. Again, these are created in the same way as the other objects, that is, oXML.$createprocessinginstruction(), then the processing instruction is added as a child of an element.

Entities

Entities are declared in the DOM document's DocumentType object. The oXML component is based on DOM level 2, which does not support the editing or creation of DocumentType objects. Therefore, the oXML component only allows the reading of entities already defined in an existing XML document.

Saving the XML File

Once you have created your DOM document in Omnis, with all the elements and so on in place, you need to save the document object to an .xml file. To do this, you can use the $savefile() method in the DOM document object.

Do oXML.$savefile("C:\MyFolder\MyXML.xml", lError, kFalse, kXMLFormatFull)

The last argument of the $savefile() method allows you to specify the formatting of the output XML file. The formatting options let you specify whether or not to add carriage returns and line feeds, and to remove spaces, etc. Different parsers may require different formatting settings to display your XML file.

There are various other methods within the DOM document object, which may also be useful to you. But the basics described in this tech note should be enough for most situations, and should give you a good idea about using these other methods.

You can download an example library from GitHub: https://github.com/OmnisStudio/Omnis-XML (for Studio 8.1.2 or above)
(or the archive: XMLex.zip for Studio 4 or above, may require conversion).