Javascript XML

From Yate Documentation
Jump to: navigation, search

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])

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
Return:
XML string.

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

s:

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

ss:

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

Personal tools
Namespaces

Variants
Actions
Preface
Configuration
Administrators
Developers