Writing XML in Scripts

To use the write, set any required handlers for the XML document (addHandler() function) and then call one of the write functions (toFile() or toString()) to write an object as an XML document. The writer will call a handler each time it finds an element that matches the handler pattern.

XML Document Mapping

The default document mapping is:

A script object will be mapped to an XML element with the same name (see XMLWriter for constraints on object and property names that will not map into the XML Standard.
XML elements will be added to their parent XML elements.
The value of the script object will become the text in an XML element.
The attributes in a script object returned by calling the function getAttributes() on the script object will become the attributes of the XML element.

For example the following script object:

om.a

om.a.b (has an attribute att=”an attribute” )

om.a.b.c[] (is an array of 4 elements)

om.a.d (has a value of “Element d”)

maps to the following XML document -

<a>

<c>First</c>

<c>Second</c>

<c>Third</c>

<c>Fourth</c>

</b>

<d>Element d</d>

</a>

Note that the XML starts from the property 'a' held by variable 'om'. The variable 'om' is a container that holds a single property that is the start of the object model. If there is more than one property in variable 'om' then the XML formed will have more than one top level element, this is not 'well formed' XML and will cause an error if an attempt is made to parse it. This is not considered as an error in the writer however, as the XML being written may be only part of a complete XML document.

The XML written will also not be 'well formed' if the property in variable 'om' is an array as this will also result in XML with more than one top level element.

Pattern Matching

A pattern is a string which consists of one or more element names and optional selection criteria enclosed in square brackets separated by forward slashes.

e.g.

"/" will match the root element of the XML document.

"/a/b/c" will match all "c" elements whose parent is a "b" element and whose grandparent is the root element "a".

"a/b/c" will match all "c" elements whose parent is a "b" element and grandparent is the element "a" irrespective of where they occur in the document.

"c" will match all "c" elements irrespective of where they occur in the document.

"b/c[2]" will match all the second c that has a parent of b.

"b/c[2][@warning = 'true'] " will match all the second c that has an attribute named warning whose value is 'true' that has a parent of b.

When a pattern is matched the handler function will be called.

e.g.

om.a
om.a.b
om.a.b.c[]
om.a.d

Using the example shown above:

The pattern is "b" or "a/b" or "/a/b" (these all refer to element b).
The handler function would be called with two parameters.
The first parameter would have no value but would have a property called "c" that would be an array containing four elements that would have the values "First", "Second", "Third" and "Fourth".
Calling getAttributes() on the parameter would return an object whose value would have a value of 1 and would contain one property whose name would be "att" and whose value would be "an attribute".

Handler Functions

The handler function is called by the writer when an element matching the handler pattern is detected. This call is done before the start element is written. This means that the element and all its child elements have not yet been written.

The handler function is passed two or more parameters , the first parameter is a script compound object that represents the child elements of the matching node, the second parameter is a reference to the XMLWriter that is being used to perform this write, the remaining parameters are the optional parameters given at the end of the addHandler method call.

When the XMLWriter calls a handler function it expects that function to provide the string to be written for the element. The writer will take the returned data from the handler function and write that instead of its own object-to-XML string. This includes all the child objects of the matching object. This means that the handler function needs to return an XML string representing the matched object and all its child objects.

e.g.

function writeHandler(element, parser, name) {

var output = ''+name;

var attributes = element.getAttributes();

for (attribute in attributes) {

output += attribute+'=”'+attributes[attribute]+'”';

}

output += ''+element+'/'+name+'';

return output;

}

In this example the addHandler() function (not shown) included an extra parameter that was the name of the element. The element was assumed to have no properties (i.e. no child elements). The attribute data was enclosed in quotes.

CDATA Sections

CDATA Sections are used to escape blocks of text containing characters which would otherwise be recognized as markup. All tags and entity references are ignored by an XML processor that treats them just like any character data. CDATA blocks have been provided as a convenience measure when you want to include large blocks of special characters as character data, but you do not want to have to use entity references all the time.

The XMLWriter constructor will accept a Boolean argument that will determine whether or not the element data is written inside CDATA sections.

e.g.

var xw = new XMLWriter(true);

xw.toString(om);

This will produce the following output:

<a>

</b>

</a>

Comment on this topic

Topic ID: 150116