XmlFile Class (Write XML Files)

Overview

XmlFile is a JavaScript class that can be used to open and write XML data to any file. (As of 3.1.001.01) See XmlInput for the DocOrigin script function for reading XML files.)

You can create an XmlFile object as follows:

var oXml = new XmlFile(sFilePath[, bSuppressDefaultXmlTags[, bOpenNow]]);

where

*sFilePath*	(Mandatory) A string representing the output file path.
bSuppressDefaultXmlTags	(As of 3.1.002.02) A Boolean which defines whether to suppress the `<XMLData>` and `<Document>` tags. Default is false.
*bOpenNow*	(As of 3.1.002.02) A Boolean which defines whether to immediately open and create the output file, versus delay until some tag or data output call is made. Default is false.

This will create the oXml object with the specified file as an XML output file. Subsequent function calls or property assignments can be used to specify the XML tags and data to store in the output file. When you are finished you should close the file using the oXml.close() function. When the file is closed, all outstanding closing XML tags are automatically added to complete the file. The XmlFile functions ensure that you create properly structured XML. It tracks open sub-structures and ensures the closing </end> tags are inserted as required.

Functions

In the following table, oXml is used as an example of an XmlFile object name, but you can use any name. It would be created with:

 var oXml = new XmlFile ("somefile.xml", bSuppressDefaultXmlTags, bOpenNow);

After creating the object you may use any of the following functions:

`oXml.`*close*`()`	Close the file. If bOpenNow is false and no output has been written, the output file is not created. All required ending tags are automatically added. Once the file is closed, it is available for opening by any other application.
`oXml.`*getFileName*`()`	Return the name of the XML file. This returns the name of the file that this object opened. This can be useful when the XmlFile Class has been created by another process such as when a Merge filter script is given the `_xml` object. In the example above it would return `somefile.xml`.
`oXml.`*newDocument*`()`	Begin a new document. This closes off any previous non-empty document with a `</Document>` close-tag; and then starts a new document with the `<Document>` open-tag. If bSuppressDefaultXmlTags is true or if there is a still-empty document already open, this function does nothing.
`oXml.`pi`(`*string*`)`	Insert an XML Processing Instruction. This will insert an XML processing instruction `<?` *string* `?>` into the output file.
`oXml.`*comment`(`string*`)`	Add *string* as an XML comment. `<!--` *string* `-->`
`oXml.`*tag`(`tagname`[,` attrs*`])`	Begin a new XML group. A new XML group `<tagname>` is added to the output file as the start tag of the enclosing element for all the subsequent data up to the next `oXml.`*endTag`()` call. For every `oXml.`tag`()` call there must be a matching `oXml.`endTag`()` call. (As of 3.1.002.10) attrs* is optional; it is either a "formatted attributes string", e.g. `'attr1="value1" attr2="value2"'` or an object `{attr1:"value1", attr2:"value2", ...}`.
`oXml.`*endTag*`()`	End the current XML group.
`oXml.`*set`(`tag`,` value`[,` attrs*`])`	Add `<tag>value</tag>` to the output. (As of 3.1.002.10) attrs were introduced.

Writing Data

You can assign data values or structures to any named property of the oXml object. This will cause the data to be inserted inside appropriate XML tags. As an example:

 oXml.mydata = "This is my data";
 oXml.another = "more stuff";

Results in XML output of:

 <mydata>This is my data</mydata>
 <another>more stuff</another>

As of 3.1.002.10, there is a special __attrs__ property available for assigning XML attributes via JavaScript objects. See an example below.

Example

You may also assign entire JavaScript object structures to the oXml object as in:

oXml.mydata = { __attrs__: { comment: "This is the mydata tag" },
	Detail: { __attrs__: {comment: "This is the Detail tag"},
		Name:'Bert',
		Addr:'123 Sesame Street'
	}
};
Results in XML output of:

Results in XML output of:

<mydata comment="This is the mydata tag">
	<Detail comment="This is the Detail tag">
		<Name>Bert</Name>
		<Addr>123 Sesame Street</Addr>
	</Detail>
</mydata>

These structures can be nested to any depth.

var myfile = new XmlFile("myfile.xml");
myfile.tag("Header");
myfile.comment = "This is my address info.";
myfile.Name = "Bert";
myfile.Phone = "555-555-5555";
myfile.Address = {Addr1:"123 Sesame Street",
                  Addr2:"New York",
                  Addr3:"USA"};
myfile.endTag();
myfile.close();

Will create the following XML:

<?xml version="1.0" encoding="UTF-8"?>
<XMLData>
	<Document>
		<Header>
			<comment>This is my address info.</comment>
			<Name>Bert</Name>
			<Phone>555-555-5555</Phone>
			<Address>
				<Addr1>123 Sesame Street</Addr1>
				<Addr2>New York</Addr2>
				<Addr3>USA</Addr3>
			</Address>
		</Header>
	</Document>
</XMLData>

The

oXml.tag = {tag1:"value1", tag2:"value2", … tagn:"valuen"};

usage is very powerful. The within-curly-braces syntax is really defining a JavaScript object. Of course, if you happen to have a JavaScript object already available, constructed through whatever prior processing, you can output the elements of that object to XML simply by saying:

oXml.tag = objectName;

The elements of the object will be iterated over and an XML element will be emitted for each. The group of elements will be encased in the usual way with the specified <tag> bookends. This is quite powerful when constructing XML data files based on your own application's objects.

_xml

When processing DocOrigin Merge filter scripts a special instance of the XmlFile object is automatically created. It is called _xml and is pre-programmed to output to the temporary file Merge will use as the filtered output data stream. All of the above methods will work with the object named _xml.

_summary

Merge also provides a second XmlFile object named _summary. It can be used to create data for a Merge summary document.