1 /*

     2 YUI 3.10.3 (build 2fb5187)

     3 Copyright 2013 Yahoo! Inc. All rights reserved.

     4 Licensed under the BSD License.

     5 http://yuilibrary.com/license/

     6 */

     7 

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

     9 

    10 /**

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

    12  * stored in arrays.

    13  *

    14  * @module dataschema

    15  * @submodule dataschema-array

    16  */

    17 

    18 /**

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

    20 stored in arrays.

    21 

    22 See the `apply` method below for usage.

    23 

    24 @class DataSchema.Array

    25 @extends DataSchema.Base

    26 @static

    27 **/

    28 var LANG = Y.Lang,

    29 

    30     SchemaArray = {

    31 

    32         ////////////////////////////////////////////////////////////////////////

    33         //

    34         // DataSchema.Array static methods

    35         //

    36         ////////////////////////////////////////////////////////////////////////

    37 

    38         /**

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

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

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

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

    43         property will be added.

    44 

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

    46 

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

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

    49 

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

    51 

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

    53         `response.results` array.

    54 

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

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

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

    58         values.

    59 

    60         If the input array contains objects, the identified

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

    62         objects for the output result.

    63 

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

    65 

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

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

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

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

    70                 return a value.

    71 

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

    73         instead of objects (see example below).

    74 

    75         @example

    76             // Process array of arrays

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

    78                 data = [

    79                     [ 'Banana', 'yellow' ],

    80                     [ 'Orange', 'orange' ],

    81                     [ 'Eggplant', 'purple' ]

    82                 ];

    83 

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

    85 

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

    87 

    88             

    89             // Process array of objects

    90             data = [

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

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

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

    94             ];

    95 

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

    97 

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

    99 

   100 

   101             // Use parsers

   102             schema.resultFields = [

   103                 {

   104                     key: 'fruit',

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

   106                 },

   107                 {

   108                     key: 'price',

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

   110                 }

   111             ];

   112 

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

   114 

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

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

   117          

   118         @method apply

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

   120             properties are:

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

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

   123               details.

   124         @param {Array} data Array data.

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

   126         @static

   127         **/

   128         apply: function(schema, data) {

   129             var data_in = data,

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

   131 

   132             if(LANG.isArray(data_in)) {

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

   134                     // Parse results data

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

   136                 }

   137                 else {

   138                     data_out.results = data_in;

   139                 }

   140             }

   141             else {

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

   143             }

   144 

   145             return data_out;

   146         },

   147 

   148         /**

   149          * Schema-parsed list of results from full data

   150          *

   151          * @method _parseResults

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

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

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

   155          * @return {Object} Parsed data object.

   156          * @static

   157          * @protected

   158          */

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

   160             var results = [],

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

   162 

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

   164                 result = {};

   165                 item = array_in[i];

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

   167                 if(type > 0) {

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

   169                         field = fields[j];

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

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

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

   173                     }

   174                 }

   175                 else if(type === 0) {

   176                     result = item;

   177                 }

   178                 else {

   179                     //TODO: null or {}?

   180                     result = null;

   181                 }

   182                 results[i] = result;

   183             }

   184             data_out.results = results;

   185 

   186             return data_out;

   187         }

   188     };

   189 

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

   191 

   192 

   193 }, '3.10.3', {"requires": ["dataschema-base"]});