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

   1 /*
   2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.net/yui/license.txt
   5 version: 3.0.0
   6 build: 1549
   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      * Executes a given callback.  The third param determines whether to execute
  86      *
  87      * @method DataSource.issueCallback
  88      * @param callback {Object} The callback object.
  89      * @param params {Array} params to be passed to the callback method
  90      * @param error {Boolean} whether an error occurred
  91      * @static
  92      */
  93     issueCallback: function (e) {
  94         if(e.callback) {
  95             var callbackFunc = (e.error && e.callback.failure) || e.callback.success;
  96             if (callbackFunc) {
  97                 callbackFunc(e);
  98             }
  99         }
 100     }
 101 });
 102
 103 Y.extend(DSLocal, Y.Base, {
 104     /**
 105     * Internal init() handler.
 106     *
 107     * @method initializer
 108     * @param config {Object} Config object.
 109     * @private
 110     */
 111     initializer: function(config) {
 112         this._initEvents();
 113     },
 114
 115     /**
 116     * This method creates all the events for this module.
 117     * @method _initEvents
 118     * @private
 119     */
 120     _initEvents: function() {
 121         /**
 122          * Fired when a data request is received.
 123          *
 124          * @event request
 125          * @param e {Event.Facade} Event Facade with the following properties:
 126          * <dl>
 127          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 128          * <dt>request (Object)</dt> <dd>The request.</dd>
 129          * <dt>callback (Object)</dt> <dd>The callback object.</dd>
 130          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 131          * </dl>
 132          * @preventable _defRequestFn
 133          */
 134         this.publish("request", {defaultFn: Y.bind("_defRequestFn", this), queuable:true});
 135
 136         /**
 137          * Fired when raw data is received.
 138          *
 139          * @event data
 140          * @param e {Event.Facade} Event Facade with the following properties:
 141          * <dl>
 142          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 143          * <dt>request (Object)</dt> <dd>The request.</dd>
 144          * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 145          *     <dl>
 146          *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 147          *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 148          *     </dl>
 149          * </dd>
 150          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 151          * <dt>data (Object)</dt> <dd>Raw data.</dd>
 152          * </dl>
 153          * @preventable _defDataFn
 154          */
 155         this.publish("data", {defaultFn: Y.bind("_defDataFn", this), queuable:true});
 156
 157         /**
 158          * Fired when response is returned.
 159          *
 160          * @event response
 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>The callback object with the following properties:
 166          *     <dl>
 167          *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 168          *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 169          *     </dl>
 170          * </dd>
 171          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 172          * <dt>data (Object)</dt> <dd>Raw data.</dd>
 173          * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
 174          *     <dl>
 175          *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
 176          *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
 177          *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
 178          *     </dl>
 179          * </dd>
 180          * </dl>
 181          * @preventable _defResponseFn
 182          */
 183          this.publish("response", {defaultFn: Y.bind("_defResponseFn", this), queuable:true});
 184
 185         /**
 186          * Fired when an error is encountered.
 187          *
 188          * @event error
 189          * @param e {Event.Facade} Event Facade with the following properties:
 190          * <dl>
 191          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 192          * <dt>request (Object)</dt> <dd>The request.</dd>
 193          * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 194          *     <dl>
 195          *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 196          *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 197          *     </dl>
 198          * </dd>
 199          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 200          * <dt>data (Object)</dt> <dd>Raw data.</dd>
 201          * <dt>response (Object)</dt> <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 (Object)</dt> <dd>Error object.</dd>
 206          *     </dl>
 207          * </dd>
 208          * </dl>
 209          */
 210
 211     },
 212
 213     /**
 214      * Manages request/response transaction. Must fire <code>response</code>
 215      * event when response is received. This method should be implemented by
 216      * subclasses to achieve more complex behavior such as accessing remote data.
 217      *
 218      * @method _defRequestFn
 219      * @param e {Event.Facade} Event Facadewith 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>The callback object with the following properties:
 224      *     <dl>
 225      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 226      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 227      *     </dl>
 228      * </dd>
 229      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 230      * </dl>
 231      * @protected
 232      */
 233     _defRequestFn: function(e) {
 234         var data = this.get("source");
 235
 236         // Problematic data
 237         if(LANG.isUndefined(data)) {
 238             e.error = new Error("Local source undefined");
 239         }
 240         if(e.error) {
 241             this.fire("error", e);
 242         }
 243
 244         this.fire("data", Y.mix({data:data}, e));
 245     },
 246
 247     /**
 248      * Normalizes raw data into a response that includes results and meta properties.
 249      *
 250      * @method _defDataFn
 251      * @param e {Event.Facade} Event Facade with the following properties:
 252      * <dl>
 253      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 254      * <dt>request (Object)</dt> <dd>The request.</dd>
 255      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 256      *     <dl>
 257      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 258      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 259      *     </dl>
 260      * </dd>
 261      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 262      * <dt>data (Object)</dt> <dd>Raw data.</dd>
 263      * </dl>
 264      * @protected
 265      */
 266     _defDataFn: function(e) {
 267         var data = e.data,
 268             meta = e.meta,
 269             response = {
 270                 results: (LANG.isArray(data)) ? data : [data],
 271                 meta: (meta) ? meta : {}
 272             };
 273
 274         this.fire("response", Y.mix({response: response}, e));
 275     },
 276
 277     /**
 278      * Sends data as a normalized response to callback.
 279      *
 280      * @method _defResponseFn
 281      * @param e {Event.Facade} Event Facade with the following properties:
 282      * <dl>
 283      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 284      * <dt>request (Object)</dt> <dd>The request.</dd>
 285      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 286      *     <dl>
 287      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 288      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 289      *     </dl>
 290      * </dd>
 291      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 292      * <dt>data (Object)</dt> <dd>Raw data.</dd>
 293      * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
 294      *     <dl>
 295      *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
 296      *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
 297      *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
 298      *     </dl>
 299      * </dd>
 300      * </dl>
 301      * @protected
 302      */
 303     _defResponseFn: function(e) {
 304         // Send the response back to the callback
 305         DSLocal.issueCallback(e);
 306     },
 307
 308     /**
 309      * Generates a unique transaction ID and fires <code>request</code> event.
 310      *
 311      * @method sendRequest
 312      * @param request {Object} Request.
 313      * @param callback {Object} An object literal with the following properties:
 314      *     <dl>
 315      *     <dt><code>success</code></dt>
 316      *     <dd>The function to call when the data is ready.</dd>
 317      *     <dt><code>failure</code></dt>
 318      *     <dd>The function to call upon a response failure condition.</dd>
 319      *     <dt><code>argument</code></dt>
 320      *     <dd>Arbitrary data payload that will be passed back to the success and failure handlers.</dd>
 321      *     </dl>
 322      * @param cfg {Object} Configuration object
 323      * @return {Number} Transaction ID.
 324      */
 325     sendRequest: function(request, callback, cfg) {
 326         var tId = DSLocal._tId++;
 327         this.fire("request", {tId:tId, request:request, callback:callback, cfg:cfg || {}});
 328         return tId;
 329     }
 330 });
 331
 332 Y.namespace("DataSource").Local = DSLocal;
 333
 334
 335
 336 }, '3.0.0' ,{requires:['base']});