[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                      Y.log("Schema resultFields property not found: " + Y.dump(schema), "warn", "dataschema-array");
 140                  }
 141              }
 142              else {
 143                  Y.log("Array data could not be schema-parsed: " + Y.dump(data) + " " + Y.dump(data), "error", "dataschema-array");
 144                  data_out.error = new Error("Array schema parse failure");
 145              }
 146  
 147              return data_out;
 148          },
 149  
 150          /**
 151           * Schema-parsed list of results from full data
 152           *
 153           * @method _parseResults
 154           * @param fields {Array} Schema to parse against.
 155           * @param array_in {Array} Array to parse.
 156           * @param data_out {Object} In-progress parsed data to update.
 157           * @return {Object} Parsed data object.
 158           * @static
 159           * @protected
 160           */
 161          _parseResults: function(fields, array_in, data_out) {
 162              var results = [],
 163                  result, item, type, field, key, value, i, j;
 164  
 165              for(i=array_in.length-1; i>-1; i--) {
 166                  result = {};
 167                  item = array_in[i];
 168                  type = (LANG.isObject(item) && !LANG.isFunction(item)) ? 2 : (LANG.isArray(item)) ? 1 : (LANG.isString(item)) ? 0 : -1;
 169                  if(type > 0) {
 170                      for(j=fields.length-1; j>-1; j--) {
 171                          field = fields[j];
 172                          key = (!LANG.isUndefined(field.key)) ? field.key : field;
 173                          value = (!LANG.isUndefined(item[key])) ? item[key] : item[j];
 174                          result[key] = Y.DataSchema.Base.parse.call(this, value, field);
 175                      }
 176                  }
 177                  else if(type === 0) {
 178                      result = item;
 179                  }
 180                  else {
 181                      //TODO: null or {}?
 182                      result = null;
 183                      Y.log("Unexpected type while parsing array: " + Y.dump(item), "warn", "dataschema-array");
 184                  }
 185                  results[i] = result;
 186              }
 187              data_out.results = results;
 188  
 189              return data_out;
 190          }
 191      };
 192  
 193  Y.DataSchema.Array = Y.mix(SchemaArray, Y.DataSchema.Base);
 194  
 195  
 196  }, '3.17.2', {"requires": ["dataschema-base"]});