Keyword Index

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();