File yui3/src/dataschema/js/dataschema-array.js
/**
* Provides a DataSchema implementation which can be used to work with data
* stored in arrays.
*
* @module dataschema
* @submodule dataschema-array
*/
/**
Provides a DataSchema implementation which can be used to work with data
stored in arrays.
See the `apply` method below for usage.
@class DataSchema.Array
@extends DataSchema.Base
@static
**/
var LANG = Y.Lang,
SchemaArray = {
////////////////////////////////////////////////////////////////////////
//
// DataSchema.Array static methods
//
////////////////////////////////////////////////////////////////////////
/**
Applies a schema to an array of data, returning a normalized object
with results in the `results` property. The `meta` property of the
response object is present for consistency, but is assigned an empty
object. If the input data is absent or not an array, an `error`
property will be added.
The input array is expected to contain objects, arrays, or strings.
If _schema_ is not specified or _schema.resultFields_ is not an array,
`response.results` will be assigned the input array unchanged.
When a _schema_ is specified, the following will occur:
If the input array contains strings, they will be copied as-is into the
`response.results` array.
If the input array contains arrays, `response.results` will contain an
array of objects with key:value pairs assuming the fields in
_schema.resultFields_ are ordered in accordance with the data array
values.
If the input array contains objects, the identified
_schema.resultFields_ will be used to extract a value from those
objects for the output result.
_schema.resultFields_ field identifiers are objects with the following properties:
* `key` : <strong>(required)</strong> The locator name (String)
* `parser`: A function or the name of a function on `Y.Parsers` used
to convert the input value into a normalized type. Parser
functions are passed the value as input and are expected to
return a value.
If no value parsing is needed, you can use strings as identifiers
instead of objects (see example below).
@example
// Process array of arrays
var schema = { resultFields: [ 'fruit', 'color' ] },
data = [
[ 'Banana', 'yellow' ],
[ 'Orange', 'orange' ],
[ 'Eggplant', 'purple' ]
];
var response = Y.DataSchema.Array.apply(schema, data);
// response.results[0] is { fruit: "Banana", color: "yellow" }
// Process array of objects
data = [
{ fruit: 'Banana', color: 'yellow', price: '1.96' },
{ fruit: 'Orange', color: 'orange', price: '2.04' },
{ fruit: 'Eggplant', color: 'purple', price: '4.31' }
];
response = Y.DataSchema.Array.apply(schema, data);
// response.results[0] is { fruit: "Banana", color: "yellow" }
// Use parsers
schema.resultFields = [
{
key: 'fruit',
parser: function (val) { return val.toUpperCase(); }
},
{
key: 'price',
parser: 'number' // Uses Y.Parsers.number
}
];
response = Y.DataSchema.Array.apply(schema, data);
// Note price was converted from a numeric string to a number
// response.results[0] looks like { fruit: "BANANA", price: 1.96 }
@method apply
@param {Object} [schema] Schema to apply. Supported configuration
properties are:
@param {Array} [schema.resultFields] Field identifiers to
locate/assign values in the response records. See above for
details.
@param {Array} data Array data.
@return {Object} An Object with properties `results` and `meta`
@static
**/
apply: function(schema, data) {
var data_in = data,
data_out = {results:[],meta:{}};
if(LANG.isArray(data_in)) {
if(schema && LANG.isArray(schema.resultFields)) {
// Parse results data
data_out = SchemaArray._parseResults.call(this, schema.resultFields, data_in, data_out);
}
else {
data_out.results = data_in;
Y.log("Schema resultFields property not found: " + Y.dump(schema), "warn", "dataschema-array");
}
}
else {
Y.log("Array data could not be schema-parsed: " + Y.dump(data) + " " + Y.dump(data), "error", "dataschema-array");
data_out.error = new Error("Array schema parse failure");
}
return data_out;
},
/**
* Schema-parsed list of results from full data
*
* @method _parseResults
* @param fields {Array} Schema to parse against.
* @param array_in {Array} Array to parse.
* @param data_out {Object} In-progress parsed data to update.
* @return {Object} Parsed data object.
* @static
* @protected
*/
_parseResults: function(fields, array_in, data_out) {
var results = [],
result, item, type, field, key, value, i, j;
for(i=array_in.length-1; i>-1; i--) {
result = {};
item = array_in[i];
type = (LANG.isObject(item) && !LANG.isFunction(item)) ? 2 : (LANG.isArray(item)) ? 1 : (LANG.isString(item)) ? 0 : -1;
if(type > 0) {
for(j=fields.length-1; j>-1; j--) {
field = fields[j];
key = (!LANG.isUndefined(field.key)) ? field.key : field;
value = (!LANG.isUndefined(item[key])) ? item[key] : item[j];
result[key] = Y.DataSchema.Base.parse.call(this, value, field);
}
}
else if(type === 0) {
result = item;
}
else {
//TODO: null or {}?
result = null;
Y.log("Unexpected type while parsing array: " + Y.dump(item), "warn", "dataschema-array");
}
results[i] = result;
}
data_out.results = results;
return data_out;
}
};
Y.DataSchema.Array = Y.mix(SchemaArray, Y.DataSchema.Base);