[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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.17.2', {"requires": ["dataschema-base"]});