1 YUI.add('dataschema-array', function (Y, NAME) {

     2 

     3 /**

     4  * Provides a DataSchema implementation which can be used to work with data

     5  * stored in arrays.

     6  *

     7  * @module dataschema

     8  * @submodule dataschema-array

     9  */

    10 

    11 /**

    12 Provides a DataSchema implementation which can be used to work with data

    13 stored in arrays.

    14 

    15 See the `apply` method below for usage.

    16 

    17 @class DataSchema.Array

    18 @extends DataSchema.Base

    19 @static

    20 **/

    21 var LANG = Y.Lang,

    22 

    23     SchemaArray = {

    24 

    25         ////////////////////////////////////////////////////////////////////////

    26         //

    27         // DataSchema.Array static methods

    28         //

    29         ////////////////////////////////////////////////////////////////////////

    30 

    31         /**

    32         Applies a schema to an array of data, returning a normalized object

    33         with results in the `results` property. The `meta` property of the

    34         response object is present for consistency, but is assigned an empty

    35         object.  If the input data is absent or not an array, an `error`

    36         property will be added.

    37 

    38         The input array is expected to contain objects, arrays, or strings.

    39 

    40         If _schema_ is not specified or _schema.resultFields_ is not an array,

    41         `response.results` will be assigned the input array unchanged.

    42 

    43         When a _schema_ is specified, the following will occur:

    44 

    45         If the input array contains strings, they will be copied as-is into the

    46         `response.results` array.

    47 

    48         If the input array contains arrays, `response.results` will contain an

    49         array of objects with key:value pairs assuming the fields in

    50         _schema.resultFields_ are ordered in accordance with the data array

    51         values.

    52 

    53         If the input array contains objects, the identified

    54         _schema.resultFields_ will be used to extract a value from those

    55         objects for the output result.

    56 

    57         _schema.resultFields_ field identifiers are objects with the following properties:

    58 

    59           * `key`   : <strong>(required)</strong> The locator name (String)

    60           * `parser`: A function or the name of a function on `Y.Parsers` used

    61                 to convert the input value into a normalized type.  Parser

    62                 functions are passed the value as input and are expected to

    63                 return a value.

    64 

    65         If no value parsing is needed, you can use strings as identifiers

    66         instead of objects (see example below).

    67 

    68         @example

    69             // Process array of arrays

    70             var schema = { resultFields: [ 'fruit', 'color' ] },

    71                 data = [

    72                     [ 'Banana', 'yellow' ],

    73                     [ 'Orange', 'orange' ],

    74                     [ 'Eggplant', 'purple' ]

    75                 ];

    76 

    77             var response = Y.DataSchema.Array.apply(schema, data);

    78 

    79             // response.results[0] is { fruit: "Banana", color: "yellow" }

    80 

    81 

    82             // Process array of objects

    83             data = [

    84                 { fruit: 'Banana', color: 'yellow', price: '1.96' },

    85                 { fruit: 'Orange', color: 'orange', price: '2.04' },

    86                 { fruit: 'Eggplant', color: 'purple', price: '4.31' }

    87             ];

    88 

    89             response = Y.DataSchema.Array.apply(schema, data);

    90 

    91             // response.results[0] is { fruit: "Banana", color: "yellow" }

    92 

    93 

    94             // Use parsers

    95             schema.resultFields = [

    96                 {

    97                     key: 'fruit',

    98                     parser: function (val) { return val.toUpperCase(); }

    99                 },

   100                 {

   101                     key: 'price',

   102                     parser: 'number' // Uses Y.Parsers.number

   103                 }

   104             ];

   105 

   106             response = Y.DataSchema.Array.apply(schema, data);

   107 

   108             // Note price was converted from a numeric string to a number

   109             // response.results[0] looks like { fruit: "BANANA", price: 1.96 }

   110 

   111         @method apply

   112         @param {Object} [schema] Schema to apply.  Supported configuration

   113             properties are:

   114           @param {Array} [schema.resultFields] Field identifiers to

   115               locate/assign values in the response records. See above for

   116               details.

   117         @param {Array} data Array data.

   118         @return {Object} An Object with properties `results` and `meta`

   119         @static

   120         **/

   121         apply: function(schema, data) {

   122             var data_in = data,

   123                 data_out = {results:[],meta:{}};

   124 

   125             if(LANG.isArray(data_in)) {

   126                 if(schema && LANG.isArray(schema.resultFields)) {

   127                     // Parse results data

   128                     data_out = SchemaArray._parseResults.call(this, schema.resultFields, data_in, data_out);

   129                 }

   130                 else {

   131                     data_out.results = data_in;

   132                 }

   133             }

   134             else {

   135                 data_out.error = new Error("Array schema parse failure");

   136             }

   137 

   138             return data_out;

   139         },

   140 

   141         /**

   142          * Schema-parsed list of results from full data

   143          *

   144          * @method _parseResults

   145          * @param fields {Array} Schema to parse against.

   146          * @param array_in {Array} Array to parse.

   147          * @param data_out {Object} In-progress parsed data to update.

   148          * @return {Object} Parsed data object.

   149          * @static

   150          * @protected

   151          */

   152         _parseResults: function(fields, array_in, data_out) {

   153             var results = [],

   154                 result, item, type, field, key, value, i, j;

   155 

   156             for(i=array_in.length-1; i>-1; i--) {

   157                 result = {};

   158                 item = array_in[i];

   159                 type = (LANG.isObject(item) && !LANG.isFunction(item)) ? 2 : (LANG.isArray(item)) ? 1 : (LANG.isString(item)) ? 0 : -1;

   160                 if(type > 0) {

   161                     for(j=fields.length-1; j>-1; j--) {

   162                         field = fields[j];

   163                         key = (!LANG.isUndefined(field.key)) ? field.key : field;

   164                         value = (!LANG.isUndefined(item[key])) ? item[key] : item[j];

   165                         result[key] = Y.DataSchema.Base.parse.call(this, value, field);

   166                     }

   167                 }

   168                 else if(type === 0) {

   169                     result = item;

   170                 }

   171                 else {

   172                     //TODO: null or {}?

   173                     result = null;

   174                 }

   175                 results[i] = result;

   176             }

   177             data_out.results = results;

   178 

   179             return data_out;

   180         }

   181     };

   182 

   183 Y.DataSchema.Array = Y.mix(SchemaArray, Y.DataSchema.Base);

   184 

   185 

   186 }, '@VERSION@', {"requires": ["dataschema-base"]});