UIZE JavaScript Framework

MODULES Uize.Xml

1. Introduction

The Uize.Xml package defines utility methods (primarily for serialization and deserialization) that are useful when handling data in the XML format.

DEVELOPERS: Chris van Rensburg

1.1. Examples

There are no dedicated showcase example pages for the Uize.Xml module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Xml module...

SEARCH

1.2. Implementation Info

The Uize.Xml module defines the Uize.Xml package under the Uize namespace.

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

STATIC METHODS

Uize.Xml.fromAttributeValue | Uize.Xml.fromAttributes | Uize.Xml.toAttributeValue | Uize.Xml.toAttributes

STATIC PROPERTIES

Uize.Xml.moduleName | Uize.Xml.pathToResources

1.2.2. Features Overridden in This Module

No features have been overridden in this module.

1.2.3. Features Inherited From Other Modules

This module has no inherited features.

1.2.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.2.5. Unit Tests

The Uize.Xml module is unit tested by the Uize.Test.Uize.Xml test module.

2. Static Methods

2.1. Uize.Xml.fromAttributeValue

Returns a string, representing the decoded form of the specified XML encoded attribute value.

SYNTAX

unencodedAttributeValueSTR = Uize.Xml.fromAttributeValue (encodedAttributeValueSTR);

This method supports decoding the full set of 252 character entities contained in the HTML 4 specification, as well as entities encoded using the forms &#nnnn; and &#xhhhh; (where nnnn and hhhh are the Unicode character code of the character in decimal and hexadecimal formats, respectively).

EXAMPLE

unencoded = Uize.Xml.fromAttributeValue (
  'solar & wind beats "fossil" fuels'
);

After executing the above statement, the variable unencoded would have the value 'solar & wind beats "fossil" fuels'.

NOTES

see also the corresponding Uize.Xml.toAttributeValue static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Xml.fromAttributes

A utility method that parses an XML formatted attributes string and returns the attributes as an object.

SYNTAX

attributesOBJ = Uize.Xml.fromAttributes (attributesSTR);

EXAMPLE

Uize.Xml.fromAttributes ('src="myimage.gif" width="640" height="480" alt="My Image"');

With the above attributes string, the Uize.Xml.fromAttributes method would produce the object...

{
  src:'myimage.gif',
  width:'640',
  height:'480',
  alt:'My Image'
}

VARIATION

attributesOBJ = Uize.Xml.fromAttributes (attributesSTR,optionsOBJ);

The optional optionsOBJ parameter lets you qualify how the specified attributes string should be decoded.

DECODING OPTIONS

{
  nameCase:nameCaseSTR // 'lower' | 'upper' | undefined (default)
}

2.2.1. nameCase

A string, specifying the case for keys in the object that is produced from decoding the attributes string.

This property is optional. By default, attribute names are left as they appear in the attributes string. This property allows us to coerce the case in order to correct for attribute strings that do not conform in our specific use case.

EXAMPLE

Uize.Xml.fromAttributes (
  'src="myimage.gif" WIDTH="640" Height="480" ALT="My Image"',
  {nameCase:'lower'}
);

The above attributes string contains attribute names in mixed case. Specifying the value 'lower' for the nameCase property of the optionsOBJ parameter will cause the decoding to produce an object with all lowercase keys, as in...

{
  src:'myimage.gif',
  width:'640',
  height:'480',
  alt:'My Image'
}

NOTES

when parsing the attributes string, all attribute values are treated as strings
see also the corresponding Uize.Xml.toAttributes static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Xml.toAttributeValue

Returns a string, representing the XML attribute encoded form of the specified string.

SYNTAX

encodedAttributeValueSTR = Uize.Xml.toAttributeValue (unencodedAttributeValueSTR);

EXAMPLE

encodedValue = Uize.Xml.toAttributeValue ('solar & wind beats "fossil" fuels');

After executing the above statement, the variable encodedValue would have the value 'solar & wind beats "fossil" fuels'.

NOTES

see also the corresponding Uize.Xml.fromAttributeValue static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Xml.toAttributes

A utility method that serializes the properties of the specified object to produce an XML formatted attributes string.

SYNTAX

attributesSTR = Uize.Xml.toAttributes (attributesOBJ);

EXAMPLE

Uize.Xml.toAttributes ({
  src:'myimage.gif',
  width:'640',
  height:'480',
  alt:'My Image'
});

With the above attributesOBJ value, the Uize.Xml.toAttributes method would produce the string...

'src="myimage.gif" width="640" height="480" alt="My Image"'

VARIATION

attributesSTR = Uize.Xml.toAttributes (attributesOBJ,optionsOBJ);

The optional optionsOBJ parameter lets you qualify how the specified attributes object should be encoded to produce an attribute string.

ENCODING OPTIONS

{
  nameCase:nameCaseSTR // 'lower' | 'upper' | undefined (default)
}

2.4.1. nameCase

A string, specifying the case for attribute names that are generated from the keys of the attributes object.

This property is optional. By default, attribute names are identical to the keys in the attributes object. This property allows us to coerce the case in order to conform the attributes string for our specific use case.

EXAMPLE

Uize.Xml.toAttributes (
  {
    SRC:'myimage.gif',
    WIDTH:'640',
    HEIGHT:'480',
    ALT:'My Image'
  }
  {nameCase:'lower'}
);

The above attributes object contains keys that are all uppercase. Specifying the value 'lower' for the nameCase property of the optionsOBJ parameter will cause the encoding to produce an attributes string with all lowercase attribute names, as in...

'src="myimage.gif" width="640" height="480" alt="My Image"'

NOTES

all attribute values are enclosed in double quotes
empty string attribute values are always fully serialized (e.g. myattribute="")
see also the corresponding Uize.Xml.fromParams static method

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Properties

3.1. Uize.Xml.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Xml.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module