pureweb.xml. XmlUtility

The XmlUtility namespace provides methods for manipulating XML.

Method Summary

addTypelessNamespace
Adds the typeless namespace to the specified element.
copyElementsFrom
Copies all of the child elements from one node to another.
decodeElementName
Decodes a transmittable element name into a string, and returns the decoded name.
encodeElementName
Returns an encoding of the specified string that can be used as an XML element name.
getChildrenByTagName
Returns an array of immediate children of this element with the given tag name.
getOrderedChildName
Returns the name of the ordered children of the specified element, or null if there are none.
getOrderedChildren
Returns an array of the ordered children of the specified XML element.
getParentPath
Returns the normalized parent path of the specified path.
getPathComponents
Returns an array of the components on the specified path, not including the root.
getSessionElementName
Returns the name of the session element with the specified session ID.
getSessionId
Returns the ID of the session element with the specified name.
getText
Returns the text content of an element, or null if there is no text.
getTextAs
Returns the text content of an element converted to a specified data type.
getTextNodes
Returns an array containing the immediate text nodes of the specified element.
hasOrderedChildAttribute
Determines whether the specified element has an explicit ordered child attribute.
isOrderedChildName
Determines whether the specified name is an ordered child name.
moveElementsFrom
Move all of the child elements from one node to another.
newXMLCDATASection
Creates a new DOM XML CDATA section with a specified value, and returns the newly created CDATA section.
newXMLElement
Creates a new DOM XML Element with an optional internal value, and returns the newly created element.
newXMLTextNodeElement
Creates a new DOM XML TextNode Element with a specified value.
normalizePath
Normalizes an XML path and returns the normalized path as a string.
parseOrdinal
Returns a parsed ordinal from a child name.
removeWhitespaceNodes
Recursively removes whitespace nodes from an element and its descendants, and returns the modified element.
replaceAttributes
Replaces the attributes of an element with the supplied attributes.
replaceNodes
Replaces the child nodes of an element with the supplied nodes.
replaceText
Replaces the text nodes of an element.
resolvePath
Resolves the path.
setOrderedChildName
Sets the name of the ordered children of the specified element to the specified Value.
setText
Set the text content of an element.

Method Detail

<static> addTypelessNamespace(value)

Adds the typeless namespace to the specified element.
Parameters:
Name Type Description
value Element The Element to which to add the typeless namespace.

<static> copyElementsFrom(xml, source)

Copies all of the child elements from one node to another.
Parameters:
Name Type Description
xml Element The destination Element to copy to.
source Element The source Element to copy elements from.
Throws:
If either xml or source is null or undefined:
pureweb.NullArgumentException

<static> decodeElementName(elementName) → {string}

Decodes a transmittable element name into a string, and returns the decoded name.
Parameters:
Name Type Description
elementName string The name to decode.
Throws:
If elementName is null or undefined:
pureweb.NullArgumentException

<static> encodeElementName(elementName) → {string}

Returns an encoding of the specified string that can be used as an XML element name.
Parameters:
Name Type Argument Description
elementName string <nullable>
The string to encode.
Throws:
If elementName is null, undefined, or empty:
pureweb.IllegalArgumentException

<static> getChildrenByTagName(element, tagName) → {Array}

Returns an array of immediate children of this element with the given tag name.
Parameters:
Name Type Description
element Element The element.
tagName string The tag name.
Throws:
If element or tagName is null or undefined:
pureweb.NullArgumentException

<static> getOrderedChildName(value) → {string}

Returns the name of the ordered children of the specified element, or null if there are none.
Parameters:
Name Type Description
value Element the element value to check for ordered children.
Throws:

<static> getOrderedChildren(xml, orderedName) → {Array}

Returns an array of the ordered children of the specified XML element.
Parameters:
Name Type Description
xml Element The xml.
orderedName string The name of the ordered children.
Throws:
If xml is null or undefined:
pureweb.NullArgumentException

<static> getParentPath(path, isPathNormalized) → {string}

Returns the normalized parent path of the specified path. Will return null if the path is null, empty, or '/'.
Parameters:
Name Type Description
path string The path.
isPathNormalized boolean Set to true if the path is normalized, otherwise set to false.

<static> getPathComponents(path) → {Array}

Returns an array of the components on the specified path, not including the root.
Parameters:
Name Type Argument Description
path string <nullable>
The path.

<static> getSessionElementName(sessionId) → {string}

Returns the name of the session element with the specified session ID.
Parameters:
Name Type Description
sessionId string The GUID of the session.

<static> getSessionId(elementName) → {string}

Returns the ID of the session element with the specified name.
Parameters:
Name Type Description
elementName string The session element name.

<static> getText(args) → {string|null}

Returns the text content of an element, or null if there is no text.
Parameters:
Name Type Description
args Object | Object Overload 1: The XML element from which to get the text.
Overload 2: The Element and childPath from which to get the value.
Throws:

<static> getTextAs(args, type) → {?}

Returns the text content of an element converted to a specified data type. Will return null if no conversion was possible.
Parameters:
Name Type Description
args Object Parent element and optional childPath
type function The constructor function for the type you want to attempt the conversion to.
Throws:
If type is null or undefined:
pureweb.NullArgumentException

<static> getTextNodes(value) → {Array}

Returns an array containing the immediate text nodes of the specified element.
Parameters:
Name Type Description
value Element The element to search.
Throws:
If value is null or undefined:
pureweb.NullArgumentException

<static> hasOrderedChildAttribute(value) → {boolean}

Determines whether the specified element has an explicit ordered child attribute. Will return true if it does, and false otherwise.
Parameters:
Name Type Description
value Element The element value to check.

<static> isOrderedChildName(name) → {boolean}

Determines whether the specified name is an ordered child name. Returns true if the name is an ordered child name, otherwise returns false.
Parameters:
Name Type Description
name string The name.

<static> moveElementsFrom(xml, source)

Move all of the child elements from one node to another.
Parameters:
Name Type Description
xml Element The destination Element to move to.
source Element The source Element to move elements from.
Throws:
If either xml or source is null or undefined:
pureweb.NullArgumentException

<static> newXMLCDATASection(value) → {CDATASection}

Creates a new DOM XML CDATA section with a specified value, and returns the newly created CDATA section.
Parameters:
Name Type Description
value string The text for the new CDATA node.

<static> newXMLElement(name, args) → {Element}

Creates a new DOM XML Element with an optional internal value, and returns the newly created element.
Parameters:
Name Type Description
name string The name of the new element.
args Object | null | undefined The value for the new element.
Throws:
If name is null or undefined:
pureweb.NullArgumentException

<static> newXMLTextNodeElement(value) → {Node}

Creates a new DOM XML TextNode Element with a specified value.
Parameters:
Name Type Description
value string The text for the new text node element.
Returns: the new text node element.

<static> normalizePath(path) → {string}

Normalizes an XML path and returns the normalized path as a string.
Parameters:
Name Type Argument Description
path string <nullable>
The path to be normalized.

<static> parseOrdinal(childName) → {number}

Returns a parsed ordinal from a child name. Returns -1 for all names except those that match the pattern '#integer', in which case the integer value after the octothorpe is returned.
Parameters:
Name Type Description
childName string The name of the child

<static> removeWhitespaceNodes(elem) → {Document|Element}

Recursively removes whitespace nodes from an element and its descendants, and returns the modified element.
Parameters:
Name Type Description
elem Document | Element The Document from which to purge whitespace nodes.

<static> replaceAttributes(element, newAttributes)

Replaces the attributes of an element with the supplied attributes.
Parameters:
Name Type Description
element Element The element to modify.
newAttributes NamedNodeMap A named node map of the elements to add to this element.
Throws:
If element is null or undefined:
pureweb.NullArgumentException

<static> replaceNodes()

Replaces the child nodes of an element with the supplied nodes.
Throws:
If value is null or undefined:
pureweb.NullArgumentException

<static> replaceText(xml, newText)

Replaces the text nodes of an element.
Parameters:
Name Type Description
xml Element The element.
newText Array.<Element> | string An array of new text elements to add, or a string to add.
Throws:

<static> resolvePath(root, path, args)

Resolves the path.
Parameters:
Name Type Argument Description
root Element The xml.
path string <nullable>
The path.
args Object An array of two Boolean values that each can be set to either true or false: allowCreate and isPathNormalized.
Throws:
If root is null or undefined:
pureweb.NullArgumentException

<static> setOrderedChildName(value, childName)

Sets the name of the ordered children of the specified element to the specified Value.
Parameters:
Name Type Description
value Element The child.
childName boolean | number | string | null The name of the child to be set.
Throws:
If value is null or undefined:
pureweb.NullArgumentException

<static> setText(args)

Set the text content of an element.
Parameters:
Name Type Description
args Object | Object Overload 1: Object containing the element (XML) to be set, and the value to set it to.
Overload 2: Object containing parent (Element), childPath (Element), and the value to set it to.
Throws: