2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.com/yui/license.html
8 YUI.add('dataschema-xml', function(Y) {
11 * Provides a DataSchema implementation which can be used to work with XML data.
14 * @submodule dataschema-xml
19 * XML subclass for the DataSchema Utility.
20 * @class DataSchema.XML
21 * @extends DataSchema.Base
26 /////////////////////////////////////////////////////////////////////////////
28 // DataSchema.XML static methods
30 /////////////////////////////////////////////////////////////////////////////
32 * Applies a given schema to given XML data.
35 * @param schema {Object} Schema to apply.
36 * @param data {XMLDoc} XML document.
37 * @return {Object} Schema-parsed data.
40 apply: function(schema, data) {
41 var xmldoc = data, // unnecessary variables
42 data_out = {results:[],meta:{}};
44 if(xmldoc && xmldoc.nodeType && (9 === xmldoc.nodeType || 1 === xmldoc.nodeType || 11 === xmldoc.nodeType) && schema) {
46 data_out = SchemaXML._parseResults.call(this, schema, xmldoc, data_out);
49 data_out = SchemaXML._parseMeta.call(this, schema.metaFields, xmldoc, data_out);
52 data_out.error = new Error("XML schema parse failure");
59 * Get an XPath-specified value for a given field from an XML node or document.
61 * @method _getLocationValue
62 * @param field {String | Object} Field definition.
63 * @param context {Object} XML node or document to search within.
64 * @return {Object} Data value or null.
68 _getLocationValue: function(field, context) {
69 var locator = field.locator || field.key || field,
70 xmldoc = context.ownerDocument || context,
71 result, res, value = null;
74 result = SchemaXML._getXPathResult(locator, context, xmldoc);
75 while(res = result.iterateNext()) {
76 value = res.textContent || res.value || res.text || res.innerHTML || null;
79 return Y.DataSchema.Base.parse.call(this, value, field);
88 * Fetches the XPath-specified result for a given location in an XML node or document.
90 * @param locator {String} The XPath location.
91 * @param context {Object} XML node or document to search within.
92 * @param xmldoc {Object} XML document to resolve namespace.
93 * @return {Object} Data collection or null.
97 _getXPathResult: function(locator, context, xmldoc) {
99 if (! LANG.isUndefined(xmldoc.evaluate)) {
100 return xmldoc.evaluate(locator, context, xmldoc.createNSResolver(context.ownerDocument ? context.ownerDocument.documentElement : context.documentElement), 0, null);
104 var values=[], locatorArray = locator.split(/\b\/\b/), i=0, l=locatorArray.length, location, subloc, m, isNth;
106 // XPath is supported
108 // this fixes the IE 5.5+ issue where childnode selectors begin at 0 instead of 1
109 xmldoc.setProperty("SelectionLanguage", "XPath");
110 values = context.selectNodes(locator);
112 // Fallback for DOM nodes and fragments
114 // Iterate over each locator piece
115 for (; i<l && context; i++) {
116 location = locatorArray[i];
119 if ((location.indexOf("[") > -1) && (location.indexOf("]") > -1)) {
120 subloc = location.slice(location.indexOf("[")+1, location.indexOf("]"));
121 //XPath is 1-based while DOM is 0-based
123 context = context.children[subloc];
126 // grab attribute value @
127 else if (location.indexOf("@") > -1) {
128 subloc = location.substr(location.indexOf("@"));
129 context = subloc ? context.getAttribute(subloc.replace('@', '')) : context;
131 // grab that last instance of tagName
132 else if (-1 < location.indexOf("//")) {
133 subloc = context.getElementsByTagName(location.substr(2));
134 context = subloc.length ? subloc[subloc.length - 1] : null;
136 // find the last matching location in children
137 else if (l != i + 1) {
138 for (m=context.childNodes.length-1; 0 <= m; m-=1) {
139 if (location === context.childNodes[m].tagName) {
140 context = context.childNodes[m];
149 if (LANG.isString(context)) {
150 values[0] = {value: context};
154 values[0] = {value: context.innerHTML};
158 values = Y.Array(context.childNodes, 0, true);
163 // returning a mock-standard object for IE
167 iterateNext: function() {
168 if (this.index >= this.values.length) {return undefined;}
169 var result = this.values[this.index];
180 * Schema-parsed result field.
182 * @method _parseField
183 * @param field {String | Object} Required. Field definition.
184 * @param result {Object} Required. Schema parsed data object.
185 * @param context {Object} Required. XML node or document to search within.
189 _parseField: function(field, result, context) {
191 result[field.key] = SchemaXML._parseResults.call(this, field.schema, context, {results:[],meta:{}}).results;
194 result[field.key || field] = SchemaXML._getLocationValue.call(this, field, context);
199 * Parses results data according to schema
202 * @param xmldoc_in {Object} XML document parse.
203 * @param data_out {Object} In-progress schema-parsed data to update.
204 * @return {Object} Schema-parsed data.
208 _parseMeta: function(metaFields, xmldoc_in, data_out) {
209 if(LANG.isObject(metaFields)) {
211 xmldoc = xmldoc_in.ownerDocument || xmldoc_in;
213 for(key in metaFields) {
214 if (metaFields.hasOwnProperty(key)) {
215 data_out.meta[key] = SchemaXML._getLocationValue.call(this, metaFields[key], xmldoc);
223 * Schema-parsed result to add to results list.
225 * @method _parseResult
226 * @param fields {Array} Required. A collection of field definition.
227 * @param context {Object} Required. XML node or document to search within.
228 * @return {Object} Schema-parsed data.
232 _parseResult: function(fields, context) {
235 // Find each field value
236 for (j=fields.length-1; 0 <= j; j--) {
237 SchemaXML._parseField.call(this, fields[j], result, context);
244 * Schema-parsed list of results from full data
246 * @method _parseResults
247 * @param schema {Object} Schema to parse against.
248 * @param context {Object} XML node or document to parse.
249 * @param data_out {Object} In-progress schema-parsed data to update.
250 * @return {Object} Schema-parsed data.
254 _parseResults: function(schema, context, data_out) {
255 if (schema.resultListLocator && LANG.isArray(schema.resultFields)) {
256 var xmldoc = context.ownerDocument || context,
257 fields = schema.resultFields,
259 node, result, nodeList, i=0;
261 if (schema.resultListLocator.match(/^[:\-\w]+$/)) {
262 nodeList = context.getElementsByTagName(schema.resultListLocator);
264 // loop through each result node
265 for (i=nodeList.length-1; 0 <= i; i--) {
266 results[i] = SchemaXML._parseResult.call(this, fields, nodeList[i]);
270 nodeList = SchemaXML._getXPathResult(schema.resultListLocator, context, xmldoc);
272 // loop through the nodelist
273 while (node = nodeList.iterateNext()) {
274 results[i] = SchemaXML._parseResult.call(this, fields, node);
279 if (results.length) {
280 data_out.results = results;
283 data_out.error = new Error("XML schema result nodes retrieval failure");
290 Y.DataSchema.XML = Y.mix(SchemaXML, Y.DataSchema.Base);
294 }, '3.3.0' ,{requires:['dataschema-base']});