Javascript XML

Revision as of 12:40, 9 September 2024

Javascript XML.

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

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

Methods

• put(list, field_name [, addText])

Put the XML (a copy of it) in a list (usually a Message() object).
Parameters:
list: Destination object
field_name: Field name to use
addText: Optional. Add xml string also

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.

• 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.

• 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.

• 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. 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 (elements 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.