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