Caplin Trader 4.8.0

Class: module:caplin/core/XmlUtility

module:caplin/core/XmlUtility

Constructor

new module:caplin/core/XmlUtility()

Utility class that provides methods for manipulating and interacting with XML.

The module:caplin/core/XmlUtility.encodeValue and module:caplin/core/XmlUtility.decodeValue methods allow data that need to be stored and retrieved from XML to be encoded such that it doesn't contain illegal characters. The table below lists the characters that need to be encoded in this way.

This is a static class that never needs to be instantiated.

Description Decoded Encoded
less than < &lt;
greater than > &gt;
ampersand & &amp;
apostrophe ' &apos;
quotation mark " &quot;

Methods

(static) convertXmlNodeToAttributesMap(oXmlNode) → {Object}

Loops through all the attributes defined on the specified XML node and extracts them to an object literal. Only the attributes on the specified XML node will be inserted into the map - any attributes on child nodes will be ignored.

Each of the values that are retrieved from the XML node's attribute have been decoded.

Parameters:
Name Type Description
oXmlNode XmlNode The XML node to be converted.
Returns:
A map of name/value pairs for all the attributes defined in the specified XML node.
Type
Object

(static) copyNodeAttributes(oSourceXmlNode, oTargetXmlNode)

Copy the attributes from the given source node, to the given target node.
Parameters:
Name Type Description
oSourceXmlNode XmlNode the node from which the attributes will be copied from.
oTargetXmlNode XmlNode the node to which the attributes will be copied to.

(static) decodeValue(sValueToDecode) → {String}

Decodes the specified value and returns the result. This method reverts the encoding performed by the module:caplin/core/XmlUtility.encodeValue method, although it will only ever return a string. For example, if a number were encoded, then a string representing that number will be decoded.

This method requires the specified value to have a valid encoding, if it doesn't then an exception will be thrown. For example, FX & FI is invalid as the encoding is missing a semicolon. Please see XmlUtility for more information on which characters are encoded.

Parameters:
Name Type Description
sValueToDecode Variant The value to be decoded. This may not be null or undefined, and it must be a valid encoding.
Throws:
if the specified value to encode is null or undefined, or if it is not one of the valid character encodings.
Type
module:caplin/core/Error
Returns:
The encoded value.
Type
String

(static) encodeValue(vValueToEncode) → {String}

Encodes specified value and returns the result, such that it can be stored as a valid value in XML. Non-Strings can be encoded, however they are converted to strings.

The module:caplin/core/XmlUtility.decodeValue method will convert the encoded value back.

Please see XmlUtility for more information on which characters are encoded.

Parameters:
Name Type Description
vValueToEncode Variant The value to be encoded. This may not be null or undefined, and all values will be converted to Strings.
Throws:
if the specified value to encode is null or undefined.
Type
module:caplin/core/Error
Returns:
The encoded value.
Type
String

(static) isValidAttributeName(sAttributeName) → {boolean}

Determines whether the specified attribute name is valid or not.

An attribute name is valid if it begins with a letter (upper or lower case) or an underscore, and is followed by any number of letters, numbers, underscores or minus signs. Expressed as a regular expression, this rule is: ^[A-Za-z_][A-Za-z0-9_-]*

Parameters:
Name Type Description
sAttributeName String The name of the attribute to be tested.
Returns:
true if the specified name is valid, otherwise false.
Type
boolean

(static) selectSingleNode(oNode, sPath) → {XmlNode}

A cross-browser implementation of the XML Element method 'selectSingleNode'.
Parameters:
Name Type Description
oNode XmlNode The root XML node.
sPath String The XPath expression to evaluate.
Returns:
The first node that matches the XPath expression.
Type
XmlNode

(static) toJson(oXml, sTab) → {String}

Converts a XML element into a JSON string. Useful for serializing JSON configurations in your layout. See module:caplin/core/JsonUtility.toXml for how to convert JSON back to XML.
Parameters:
Name Type Description
oXml Object The XML object that will be converted.
sTab String Tab delimiter to use (defaults to an empty string)
Returns:
A JSON string.
Type
String