XML Data Set

Description

The Spry.Data.XMLDataSet class dervies from the HTTPSourceDataSet class so that it can load and process XML data. The XMLDataSet class makes use of XPath to identify the data within the XML data that should be flattened.

File

SpryData.js

Inheritance

Notifier -->DataSet --> HTTPSourceDataSet --> XMLDataSet

XMLDataSet constructor

Description

Spry.Data.XMLDataSet is the constructor function for the XML Data Set.

Format

Spry.Data.XMLDataSet(url, xpath, options)

Arguments

• url - The URL to the data to be loaded. This URL can be absolute, or relative to the HTML document that created the data set.
• xpath - The XPath that selects the XML nodes to flatten.
• options - An optional argument which if specified, must be an object with the option names as properties with values.
  • entityEncodeStrings
    • Boolean.
    • If true, strings that are extracted from #text and #cdata nodes in the XML DOM, during the data flattening process, are stored in the columns of the data set as entity encoded strings. If false, the strings are extracted from the #text and #cdata nodes, and stored directly into the columns of the data set. Since strings are inside #text and #cdata nodes are already entity decoded, this means that the strings are stored in the data set as entity decoded. The way the string is stored within a data set matters when the string values are used as content within a spry:region or spry:detail region. If the strings are entity encoded, the entire string is rendered as part of the region. If the strings are entity decoded, the content of the string is interpreted as HTML markup, so any <, > or & characters will have a special meaning.
    • If this option is not specified, the default behavior for the XMLDataSet is to entity encode string values.
    • In prior versions of Spry, up to and including Spry Pre-Release 1.5, only strings extracted out of #text nodes were stored as entity encoded strings. Strings extracted out of #cdata nodes were stored as entity decoded strings. This meant that entity encoded HTML markup underneath an XML tag, was treated differently from raw HTML markup that was wrapped with a CDATA tag. If developers need to restore this behavior, they can trigger a "backwards compatibility" mode by passing any value for the entityEncodeStrings option that is not a boolean value. For example, they can pass { entityEncodeStrings: -1 } to trigger the "backwards compatibility" mode. This mode will be around for a couple of releases, but it is our intention to deprecate this mode.
  • Any HTTPSourceDataSet or DataSet options.

Returns

N/A

Example

var ds = new Spry.Data.XMLDataSet("foo.php?id=100", "/foo/bar", { useCache: false, loadInterval: 1000 });

Sample

N/A

getDocument

Description

This function returns the XML DOM document the data set used to extract its data.

Format

getDocument()

Arguments

N/A

Returns

Object or null. The XML DOM Document element or null;

Example

var doc = ds.geDocument();

getXPath

Description

This function returns the current XPath.

Format

getXPath()

Arguments

N/A

Returns

String or null. Returns the XPath that will be used to extract the XML nodes for flattening. This may also return a null if one is not present.

Example

var xpathString = ds.getXPath();

loadDataIntoDataSet

Description

This function is not meant to be called directly. The XMLDataSet overrides the version of this function to add the ability to flatten an XML DOM Document.

Format

loadDataIntoDataSet(xmlDOMDoc)

Arguments

xmlDOMDoc - The data to be flattened.

Returns

N/A

Example

N/A

sessionExpiredChecker

Description

This function is not meant to be called directly. The XMLDataSet overrides the version of this function to add the ability to look for a session expired message inside XML.

Format

sessionExpiredChecker(req)

Arguments

req - Object. An instance of a Spry.Utils.loadURL.Request object.

Returns

Boolean. If true the user's session has expired.

Example

N/A

setXPath

Description

This function sets the XPath for the data set. If data has already been loaded, the XMLDataSet automatically applies the new XPath to re-generate the data for the data set.

Format

setXPath()

Arguments

N/A

Returns

N/A

Example

 ds.setXPath("//items");

xhRequestProcessor

Description

This function is not meant to be called directly. The XMLDataSet overrides the version of this function so that it returns an XML DOM Document.

Format

getURL()

Arguments

N/A

Returns

Object. The XML DOM Document or null.

Example

N/A