Javascript XML

Latest revision as of 12:08, 12 September 2024

Javascript XML.

[edit] Constructor

• new XML(obj_tag_xml)
  

Create a new XML element.
Parameters:
obj_tag_xml: Source to create from:
- Object: Create a copy if the given object is an XML element
- Tag: Create a new element with given tag
- XML string: Create a new element from XML string (it must be a complete XML)
This constructor will return the null object on failure.

x = new XML("a"); // Create from tag
x = new XML("<a><b/></a>"); // Create from XML string
xx = new XML(x); // Create a copy of x
// Failures:
x = new XML("xmlgigi");  // Invalid tag name
x = new XML("<gigi></g>");  // Invalid xml string
x = new XML("<gigi>some_text"); // Incomplete xml string
obj = new Array;
x = new XML(obj); // obj is not an XML

• new XML(tag, text)
  

Create an XML element with given tag and text.
Parameters:
tag: Element tag name. It must be a valid xml element name tag
text: Element text

This constructor generates a run time error (function call failure) if tag value is invalid.

• new XML(obj, field_name [, take])
  

Create an XML from object field. The field may be an XML element or XML string.
Parameters:
obj: Object whose field to use
field_name: Field name
take: Optional (defaults to false). Take the XML from object instead of making a copy of it. This parameter is ignored if the field is an XML string

This constructor will return the null object on failure.

obj = {xml: "<a/>"};
x = new XML(obj,"xml"); // Parse the string and build an XML element
// Obtain an xml object from a message:
x = new XML(msg,"xml",true);  // Take the xml from message
x = new XML(msg,"xml",false); // Obtain a copy of the xml element

[edit] Static Methods

• XML.loadFile(path)

Load xml from file.
Parameters:
path: File path
Return:
XML object, null on failure

The following object properties will be set:
declaration: Object with declaration attributes if one is found in the file

[edit] Methods

• put(list, field_name [, what])

Put the XML (a copy of it) in a list (usually a Message object).
Parameters:
list: Destination object
field_name: Field name to use
what: Optional. Set xml string and/or internal object. Default: XML.PutObject

• • Boolean true or XML.PutText: Put XML string only
  • Boolean false or XML.PutObject: Put XML internal object only
  • XML.PutBoth: Put XML internal object and XML string

x = new XML("a");
m = new Message("call.route");
x.put(m,"xml",true);

• getOwner()

Retrieve XML object owner (top parent).
Return:
XML object owning this XML or null if none.

• getParent()

Retrieve XML object parent.
Return:
XML parent object or null if none.

• unprefixedTag()
• getTag()

Retrieve XML tag with or without namespace prefix.

x = new XML("<some_ns:a/>");
t = x.unprefixedTag(); // "a"
t = x.getTag(); // "some_ns:a"

• getAttribute(name)

Retrieve XML attribute value.
Parameters:
name: Attribute name
Return:
Requested attribute's value, null if not found.

• setAttribute(name [, value])

Set XML attribute.
Parameters:
name: Attribute name. If value is not given name may be an object whose fields will be set as XML attributtes
value: Attribute value. Remove the attribute if value is undefined or null object

x = new XML("a");
// Set attributes
obj = {a:"a", b:"b"};
x.setAttribute(obj);

• removeAttribute(name)

Remove XML attribute.
Parameters:
name: Attribute to remove

• attributes()

Retrieve XML attributes.
Return:
Object with fields set to XML attributes. null if XML has no attribute.

• addChild(name_xml_array [, text])

Append XML child(ren).
Parameters:
name_xml_array: Child to append. This may be:
- XML tag name (append a new XML element child)
- XML element object (append a copy of given element)
- Array of XML elements (append a copy of each XML element in array)
text: Optional child text to set. This parameter is ignored if the first parameter is an array
Return:
If an XML element is added returns the added XML element or null on failure.
If an array of elements is added returns TRUE on success, FALSE on first failure.

• getChild([name] [, namespace])

Retrieve first XML child element.
Parameters:
name: Optional child tag to search for (without namespace prefix). null and undefined are treated as missing
namespace: Optional child namespace. null and undefined are treated as missing
Return:
XML element, null if not found.

• getChildByPath(path)

Retrieve first XML child element.
Parameters:
path XPath object or string with path description.
Return:
XML element, null if not found or path is invalid or path matching does not match xml elements.

• getChildren([name] [, namespace])

Retrieve XML children.
Parameters:
name: Optional child tag to search for (without namespace prefix). null and undefined are treated as missing
namespace: Optional child namespace. null and undefined are treated as missing
Return:
Array of XML elements, null if no child found.

• getChildrenByPath(path)

Retrieve XML children.
Parameters:
path XPath object or string with path description.
Return:
Array of XML elements, null if no child found or path is invalid or path matching does not match xml elements.

• getAnyByPath(path [, arr [, what]])

Generic XPath based data retrieval.
Parameters:
path XPath object or string with path description.
arr Optional array to be filled with all path matching data (XML object, string or object describing an attribute).
what Optional integer. See XPath.Find* properties for values. Default: XPath.FindAny.
Return.
First found item (XML object, string or object describing an attribute), null if not found or path is invalid or path matching does not match given search criteria.

Attribute object properties:
name: Attribute name.
value: Attribute value.

• clearChildren()

Clear all element's children, inclusing text.

NOTE: Do not use any child obtained after calling this function to avoid application crash.

var xml = new XML("<a><b/></a>");
var ch = xml.getChild("b");
xml.clearChildren();
// The following leads to application crash (invalid memory access)
var s = ch.xmlText();

• addText(text)

Add a Text child to XML element.
Parameters:
text: Text to add. The method does nothing if this parameter is null or empty string

• getText()

Retrieve XML element text.
Return:
XML text, null if not found.

• setText(text)

Set or clear XML text.
Parameters:
text: Text to set. Clear the text if this parameter is null or empty string

• getChildText([name] [, namespace])

Retrieve XML child text.
Parameters:
name: Optional child tag to search for (without namespace prefix). null and undefined are treated as missing
namespace: Optional child namespace. null and undefined are treated as missing
Return:
XML child text (may be empty), null if child is not found.

• getTextByPath(path)

Retrieve XML element text.
Parameters:
path XPath object or string with path description.
Return:
XML text, null if not found or path is invalid or path does not match an xml text.

• xmlText([spaces[,allLinesSpaces]])

Convert the XML object to string representation.
Parameters:
spaces: Optional spaces to use (verbose string build, print xml children on separate lines). Ignored if 0
allLinesSpaces: Optional fixed number of spaces to add to each line (except the first one). Ignored if 0 or spaces is 0
Return:
XML string.

x = new XML("<a attr='a'>TEXT<ch><c/></ch></a>");
s = x.xmlText();
ss = x.xmlText(2);
sss = x.xmlText(2,2);

s:

<a attr="a">TEXT<ch><c/></ch></a>

ss:

<a attr="a">
  TEXT
  <ch>
    <c/>
  </ch>
</a>

sss:

<a attr="a">
    TEXT
    <ch>
      <c/>
    </ch>
  </a>

• replaceParams(list)

Recursively replace ${paramname} in children (element attribute values and text) from parameters list.
Parameters:
list: List of parameters. Ignored if not an object (no replace is made)

• saveFile(path [, spaces])

Save xml to file.
Parameters:
path: File path
spaces: Optional number of spaces to use for indentation. Write a flat string if not given or less than 1
Return:
True on success, false on failure

The following object properties will be used to build the string to write:
declaration: XML declaration to write. May be boolean true to write a default declaration (version=1.0 encoding=utf-8) or object with declaration attributes. If an object is set the version attribute will be always written even when missing in object properties.

[edit] Static Properties

• PutObject, PutText, PutBoth

Values to be passed to put() function in what parameter.