lib/yuilib/3.13.0/datasource-local/datasource-local.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('datasource-local', function (Y, NAME) {
   9
  10 /**
  11  * The DataSource utility provides a common configurable interface for widgets to
  12  * access a variety of data, from JavaScript arrays to online database servers.
  13  *
  14  * @module datasource
  15  * @main datasource
  16  */
  17
  18 /**
  19  * Provides the base DataSource implementation, which can be extended to
  20  * create DataSources for specific data protocols, such as the IO Utility, the
  21  * Get Utility, or custom functions.
  22  *
  23  * @module datasource
  24  * @submodule datasource-local
  25  */
  26
  27 /**
  28  * Base class for the DataSource Utility.
  29  * @class DataSource.Local
  30  * @extends Base
  31  * @constructor
  32  */
  33 var LANG = Y.Lang,
  34
  35 DSLocal = function() {
  36     DSLocal.superclass.constructor.apply(this, arguments);
  37 };
  38
  39     /////////////////////////////////////////////////////////////////////////////
  40     //
  41     // DataSource static properties
  42     //
  43     /////////////////////////////////////////////////////////////////////////////
  44 Y.mix(DSLocal, {
  45     /**
  46      * Class name.
  47      *
  48      * @property NAME
  49      * @type String
  50      * @static
  51      * @final
  52      * @value "dataSourceLocal"
  53      */
  54     NAME: "dataSourceLocal",
  55
  56     /////////////////////////////////////////////////////////////////////////////
  57     //
  58     // DataSource Attributes
  59     //
  60     /////////////////////////////////////////////////////////////////////////////
  61
  62     ATTRS: {
  63         /**
  64         * @attribute source
  65         * @description Pointer to live data.
  66         * @type MIXED
  67         * @default null
  68         */
  69         source: {
  70             value: null
  71         }
  72     },
  73
  74     /**
  75      * Global transaction counter.
  76      *
  77      * @property _tId
  78      * @type Number
  79      * @static
  80      * @private
  81      * @default 0
  82      */
  83     _tId: 0,
  84
  85     /**
  86      * Global in-progress transaction objects.
  87      *
  88      * @property transactions
  89      * @type Object
  90      * @static
  91      */
  92     transactions: {},
  93
  94     /**
  95      * Returns data to callback.
  96      *
  97      * @method issueCallback
  98      * @param e {EventFacade} Event Facade.
  99      * @param caller {DataSource} Calling DataSource instance.
 100      * @static
 101      */
 102     issueCallback: function (e, caller) {
 103         var callbacks = e.on || e.callback,
 104             callback = callbacks && callbacks.success,
 105             payload = e.details[0];
 106
 107         payload.error = (e.error || e.response.error);
 108
 109         if (payload.error) {
 110             caller.fire("error", payload);
 111             callback = callbacks && callbacks.failure;
 112         }
 113
 114         if (callback) {
 115             //TODO: this should be executed from a specific context
 116             callback(payload);
 117         }
 118     }
 119 });
 120
 121 Y.extend(DSLocal, Y.Base, {
 122     /**
 123     * Internal init() handler.
 124     *
 125     * @method initializer
 126     * @param config {Object} Config object.
 127     * @private
 128     */
 129     initializer: function(config) {
 130         this._initEvents();
 131     },
 132
 133     /**
 134     * This method creates all the events for this module.
 135     * @method _initEvents
 136     * @private
 137     */
 138     _initEvents: function() {
 139         /**
 140          * Fired when a data request is received.
 141          *
 142          * @event request
 143          * @param e {Event.Facade} Event Facade with the following properties:
 144          * <dl>
 145          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 146          * <dt>request (Object)</dt> <dd>The request.</dd>
 147          * <dt>callback (Object)</dt> <dd>The callback object
 148          *   (deprecated, refer to <strong>on</strong></dd>
 149          * <dt>on (Object)</dt> <dd>The map of configured callback
 150          *   functions.</dd>
 151          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 152          * </dl>
 153          * @preventable _defRequestFn
 154          */
 155         this.publish("request", {defaultFn: Y.bind("_defRequestFn", this), queuable:true});
 156
 157         /**
 158          * Fired when raw data is received.
 159          *
 160          * @event data
 161          * @param e {Event.Facade} Event Facade with the following properties:
 162          * <dl>
 163          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 164          * <dt>request (Object)</dt> <dd>The request.</dd>
 165          * <dt>callback (Object)</dt> <dd>Deprecated alias for the
 166          *   <strong>on</strong> property</dd>
 167          * <dt>on (Object)</dt> <dd>The map of configured transaction
 168          *   callbacks.  An object with the following properties:
 169          *     <dl>
 170          *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 171          *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 172          *     </dl>
 173          * </dd>
 174          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 175          * <dt>data (Object)</dt> <dd>Raw data.</dd>
 176          * </dl>
 177          * @preventable _defDataFn
 178          */
 179         this.publish("data", {defaultFn: Y.bind("_defDataFn", this), queuable:true});
 180
 181         /**
 182          * Fired when response is returned.
 183          *
 184          * @event response
 185          * @param e {Event.Facade} Event Facade with the following properties:
 186          * <dl>
 187          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 188          * <dt>request (Object)</dt> <dd>The request.</dd>
 189          * <dt>callback (Object)</dt> <dd>Deprecated alias for the
 190          *   <strong>on</strong> property</dd>
 191          * <dt>on (Object)</dt> <dd>The map of configured transaction
 192          *   callbacks.  An object with the following properties:
 193          *     <dl>
 194          *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 195          *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 196          *     </dl>
 197          * </dd>
 198          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 199          * <dt>data (Object)</dt> <dd>Raw data.</dd>
 200          * <dt>response (Object)</dt>
 201          *     <dd>Normalized response object with the following properties:
 202          *         <dl>
 203          *             <dt>results (Object)</dt> <dd>Parsed results.</dd>
 204          *             <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
 205          *             <dt>error (Boolean)</dt> <dd>Error flag.</dd>
 206          *         </dl>
 207          *     </dd>
 208          * <dt>error</dt>
 209          *     <dd>Any error that occurred along the transaction lifecycle.</dd>
 210          * </dl>
 211          * @preventable _defResponseFn
 212          */
 213          this.publish("response", {defaultFn: Y.bind("_defResponseFn", this), queuable:true});
 214
 215         /**
 216          * Fired when an error is encountered.
 217          *
 218          * @event error
 219          * @param e {Event.Facade} Event Facade with the following properties:
 220          * <dl>
 221          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 222          * <dt>request (Object)</dt> <dd>The request.</dd>
 223          * <dt>callback (Object)</dt> <dd>Deprecated alias for the
 224          *   <strong>on</strong> property</dd>
 225          * <dt>on (Object)</dt> <dd>The map of configured transaction
 226          *   callbacks.  An object with the following properties:
 227          *     <dl>
 228          *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 229          *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 230          *     </dl>
 231          * </dd>
 232          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 233          * <dt>data (Object)</dt> <dd>Raw data.</dd>
 234          * <dt>response (Object)</dt>
 235          *     <dd>Normalized response object with the following properties:
 236          *         <dl>
 237          *             <dt>results (Object)</dt> <dd>Parsed results.</dd>
 238          *             <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
 239          *             <dt>error (Object)</dt> <dd>Error object.</dd>
 240          *         </dl>
 241          *     </dd>
 242          * <dt>error</dt>
 243          *     <dd>Any error that occurred along the transaction lifecycle.</dd>
 244          * </dl>
 245          */
 246
 247     },
 248
 249     /**
 250      * Manages request/response transaction. Must fire <code>response</code>
 251      * event when response is received. This method should be implemented by
 252      * subclasses to achieve more complex behavior such as accessing remote data.
 253      *
 254      * @method _defRequestFn
 255      * @param e {Event.Facade} Event Facadewith the following properties:
 256      * <dl>
 257      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 258      * <dt>request (Object)</dt> <dd>The request.</dd>
 259      * <dt>callback (Object)</dt> <dd>Deprecated alias for the
 260      *   <strong>on</strong> property</dd>
 261      * <dt>on (Object)</dt> <dd>The map of configured transaction
 262      *   callbacks.  An object with the following properties:
 263      *     <dl>
 264      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 265      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 266      *     </dl>
 267      * </dd>
 268      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 269      * </dl>
 270      * @protected
 271      */
 272     _defRequestFn: function(e) {
 273         var data = this.get("source"),
 274             payload = e.details[0];
 275
 276         // Problematic data
 277         if(LANG.isUndefined(data)) {
 278             payload.error = new Error("Local source undefined");
 279         }
 280
 281         payload.data = data;
 282         this.fire("data", payload);
 283     },
 284
 285     /**
 286      * Normalizes raw data into a response that includes results and meta properties.
 287      *
 288      * @method _defDataFn
 289      * @param e {Event.Facade} Event Facade with the following properties:
 290      * <dl>
 291      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 292      * <dt>request (Object)</dt> <dd>The request.</dd>
 293      * <dt>callback (Object)</dt> <dd>Deprecated alias for the
 294      *   <strong>on</strong> property</dd>
 295      * <dt>on (Object)</dt> <dd>The map of configured transaction
 296      *   callbacks.  An object with the following properties:
 297      *     <dl>
 298      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 299      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 300      *     </dl>
 301      * </dd>
 302      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 303      * <dt>data (Object)</dt> <dd>Raw data.</dd>
 304      * </dl>
 305      * @protected
 306      */
 307     _defDataFn: function(e) {
 308         var data = e.data,
 309             meta = e.meta,
 310             response = {
 311                 results: (LANG.isArray(data)) ? data : [data],
 312                 meta: (meta) ? meta : {}
 313             },
 314             payload = e.details[0];
 315
 316         payload.response = response;
 317         this.fire("response", payload);
 318     },
 319
 320     /**
 321      * Sends data as a normalized response to callback.
 322      *
 323      * @method _defResponseFn
 324      * @param e {Event.Facade} Event Facade with the following properties:
 325      * <dl>
 326      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 327      * <dt>request (Object)</dt> <dd>The request.</dd>
 328      * <dt>callback (Object)</dt> <dd>Deprecated alias for the
 329      *   <strong>on</strong> property</dd>
 330      * <dt>on (Object)</dt> <dd>The map of configured transaction
 331      *   callbacks.  An object with the following properties:
 332      *     <dl>
 333      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 334      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 335      *     </dl>
 336      * </dd>
 337      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 338      * <dt>data (Object)</dt> <dd>Raw data.</dd>
 339      * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
 340      *     <dl>
 341      *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
 342      *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
 343      *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
 344      *     </dl>
 345      * </dd>
 346      * </dl>
 347      * @protected
 348      */
 349     _defResponseFn: function(e) {
 350         // Send the response back to the callback
 351         DSLocal.issueCallback(e, this);
 352     },
 353
 354     /**
 355      * Generates a unique transaction ID and fires <code>request</code> event.
 356      * <strong>Note</strong>: the property <code>callback</code> is a
 357      * deprecated alias for the <code>on</code> transaction configuration
 358      * property described below.
 359      *
 360      * @method sendRequest
 361      * @param [request] {Object} An object literal with the following properties:
 362      *     <dl>
 363      *     <dt><code>request</code></dt>
 364      *     <dd>The request to send to the live data source, if any.</dd>
 365      *     <dt><code>on</code></dt>
 366      *     <dd>An object literal with the following properties:
 367      *         <dl>
 368      *         <dt><code>success</code></dt>
 369      *         <dd>The function to call when the data is ready.</dd>
 370      *         <dt><code>failure</code></dt>
 371      *         <dd>The function to call upon a response failure condition.</dd>
 372      *         <dt><code>argument</code></dt>
 373      *         <dd>Arbitrary data payload that will be passed back to the success and failure handlers.</dd>
 374      *         </dl>
 375      *     </dd>
 376      *     <dt><code>cfg</code></dt>
 377      *     <dd>Configuration object, if any.</dd>
 378      *     </dl>
 379      * @return {Number} Transaction ID.
 380      */
 381     sendRequest: function(request) {
 382         var tId = DSLocal._tId++,
 383             callbacks;
 384
 385         request = request || {};
 386
 387         callbacks = request.on || request.callback;
 388
 389         this.fire("request", {
 390             tId: tId,
 391             request: request.request,
 392             on: callbacks,
 393             callback: callbacks,
 394             cfg: request.cfg || {}
 395         });
 396
 397
 398         return tId;
 399     }
 400 });
 401
 402 Y.namespace("DataSource").Local = DSLocal;
 403
 404
 405 }, '3.13.0', {"requires": ["base"]});