jssource/src_files/include/javascript/yui3/build/datasource/datasource-local.js

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