Object: SPXMLFile

An SPXMLFile object provides a general way of reading objects and attributes from an XML file in a simple and structured way. Elements in the file become properties of the file object. E.g.

 f = SPXMLFile("file.xml"); 
 topObj = f.TopObj; // Assuming the top-level element in the file is "TopObj" 
 attr1 = f.TopObj.Attr1; // Gets the value of the Attr1 attribute of TopObj 
 firstInfo = f.TopObj.Info; // Gets the first element of type Info in the file 
 infos = f.TopObj.children("Info"); // Gets an array of all sub-objects of TopObj of type Info

NOTE: Tag names are case-sensitive and must be used exactly as they appear in the XML file

addChild - Adds a new child element to this element and returns the new child

children - Gets an array of the child nodes of this object, possibly filtering the list by various values.

dirty - Gets or sets the modified status of the object

firstChild - Gets a single child node of the current object with a number of filtering options.

fullName - Sets or gets the full name, including directory path, of the file.

getAttribute - Sets the value of the given attribute field.

readOnly - Gets the read-only status of the XML file. This property is read only!

save - Save the XML structure to the associated file (read from or last saved to)

saveAs - Save the XML structure to a specified file

setAttribute - Sets the value of the given attribute field.

setAttributeDataType - Sets the data type that will be returned for the given attribute field.

text - Gets the text value of this object, i.e. all text between the and delimiters of this object, or null if none exists.

xml - Gets the xml text for this object

Method: addChild

Adds a new child element to this element and returns the new child

SPXMLFile addChild(tagName);

Parameters
Name	Expected Type	Description
tagName	String	The tag name for the new element, cannot be empty

Returns:

Returns the new element

Method: children

Gets an array of the child nodes of this object, possibly filtering the list by various values.

Array children();

Array children(tagName);

Array children(tagName, attrName, attrValue, ...);

Parameters
Name	Expected Type	Description
attrName	String	The name of an attribute value to compare
attrValue	Object	This argument can be the exact desired value of the corresponding attribute or a regular expression to match against the found values. Only matching children will be returned.
tagName	String	If specified, only children of this type will be returned

Remarks:

Any number of attribute name/value pairs can be provided and they must all match exactly for the child element to be included in the returned set.
Regular expression syntax is described here

Property: dirty

Gets or sets the modified status of the object

bool dirty();

dirty = bool

Method: firstChild

Gets a single child node of the current object with a number of filtering options.

Returns:

Returns the child node or null if none was found.

Remarks:

This is a short form of (and takes the same arguments as) the children method for cases where a single child node is expected. It is equivalent to the following: c = this.children(args); (c.length > 0) ? c[0] : null;

Method: fullName

Sets or gets the full name, including directory path, of the file.

String fullName();

Returns the full path

void fullName(nameStr);

Sets the file name and path given a complete path name.

fullName = String

Sets the file name and path given a complete path name

String = fullName

Get the full path

Parameters
Name	Expected Type	Description
nameStr	String	The new path name

Remarks:

If used as a method with no arguments or a "get" property, this returns the full name, including path, of the file. If used as a method with a string argument or a "set" property, this sets the name associated with this file object. Note that this does not change the name of any file on disk, it only changes the name string of this object. Use rename to rename a file on disk.

If the file is open at the time the name is set, it will be closed.

Method: getAttribute

Sets the value of the given attribute field.

object getAttribute(name);

object getAttribute(name, type);

Parameters
Name	Expected Type	Description
name	String	The name of the attribute field to get
type	String	The optional data type that is desired. If not specified, the return value will be string.

Property: readOnly

Gets the read-only status of the XML file. This property is read only!

bool readOnly();

Method: save

Save the XML structure to the associated file (read from or last saved to)

bool save();

Method: saveAs

Save the XML structure to a specified file

bool saveAs(filePath, prompt);

Parameters
Name	Expected Type	Description
filePath	String	The full file path of the destination file
prompt	bool	If a file path is provided and this is false, the save is done with no prompt, if true, tue user is prompted with the given path as the default

Method: setAttribute

Sets the value of the given attribute field.

void setAttribute(name, value);

Parameters
Name	Expected Type	Description
value	object	The new value. This will be converted to an appropriate text format in the XML file
name	String	The name of the attribute field to set

Property: setAttributeDataType

Sets the data type that will be returned for the given attribute field.

void setAttributeDataType(name, type);

Parameters
Name	Expected Type	Description
name	String	The name of the attribute field to set
type	String	The name of the data type to return. The only allowable values are "string", "bool" and "int".

Remarks:

All data is stored in XML files as strings, so if an XML file is being accessed without any schema, all data will default to a string type. This method allows the call to force a value to be converted to the given type when the field is accessed.

Property: text

Gets the text value of this object, i.e. all text between the and delimiters of this object, or null if none exists.

String text();

Returns the text value of the object

Property: xml

Gets the xml text for this object

String xml();