# Yahoo! UI Library

### datasource 3.0.0b1

Yahoo! UI Library > datasource > datasource-local.js (source view)
Search:
Filters Show Private Show Protected Show Deprecated

    /**
     * The DataSource utility provides a common configurable interface for widgets to
     * access a variety of data, from JavaScript arrays to online database servers.
     *
     * @module datasource
     */

    /**
     * Provides the base DataSource implementation, which can be extended to
     * create DataSources for specific data protocols, such as the IO Utility, the
     * Get Utility, or custom functions.
     *
     * @module datasource
     * @submodule datasource-local
     */

    /**
     * Base class for the DataSource Utility.
     * @class DataSource.Local
     * @extends Base
     * @constructor
     */
    var LANG = Y.Lang,

    DSLocal = function() {
        DSLocal.superclass.constructor.apply(this, arguments);
    };

        /////////////////////////////////////////////////////////////////////////////
        //
        // DataSource static properties
        //
        /////////////////////////////////////////////////////////////////////////////
    Y.mix(DSLocal, {
        /**
         * Class name.
         *
         * @property NAME
         * @type String
         * @static
         * @final
         * @value "dataSourceLocal"
         */
        NAME: "dataSourceLocal",

        /////////////////////////////////////////////////////////////////////////////
        //
        // DataSource Attributes
        //
        /////////////////////////////////////////////////////////////////////////////

        ATTRS: {
            /**
            * @attribute source
            * @description Pointer to live data.
            * @type MIXED
            * @default null
            */
            source: {
                value: null
            }
        },

        /**
         * Global transaction counter.
         *
         * @property DataSource._tId
         * @type Number
         * @static
         * @private
         * @default 0
         */
        _tId: 0,

        /**
         * Executes a given callback.  The third param determines whether to execute
         *
         * @method DataSource.issueCallback
         * @param callback {Object} The callback object.
         * @param params {Array} params to be passed to the callback method
         * @param error {Boolean} whether an error occurred
         * @static
         */
        issueCallback: function (e) {
            if(e.callback) {
                var callbackFunc = (e.error && e.callback.failure) || e.callback.success;
                if (callbackFunc) {
                    callbackFunc(e);
                }
            }
        }
    });

    Y.extend(DSLocal, Y.Base, {
        /**
        * Internal init() handler.
        *
        * @method initializer
        * @param config {Object} Config object.
        * @private
        */
        initializer: function(config) {
            this._initEvents();
        },

        /**
        * This method creates all the events for this module.
        * @method _initEvents
        * @private
        */
        _initEvents: function() {
            /**
             * Fired when a data request is received.
             *
             * @event request
             * @param e {Event.Facade} Event Facade with the following properties:
             * <dl>
             * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
             * <dt>request (Object)</dt> <dd>The request.</dd>
             * <dt>callback (Object)</dt> <dd>The callback object.</dd>
             * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
             * </dl>
             * @preventable _defRequestFn
             */
            this.publish("request", {defaultFn: Y.bind("_defRequestFn", this), queuable:true});

            /**
             * Fired when raw data is received.
             *
             * @event data
             * @param e {Event.Facade} Event Facade with the following properties:
             * <dl>
             * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
             * <dt>request (Object)</dt> <dd>The request.</dd>
             * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
             *     <dl>
             *         <dt>success (Function)</dt> <dd>Success handler.</dd>
             *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
             *     </dl>
             * </dd>
             * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
             * <dt>data (Object)</dt> <dd>Raw data.</dd>
             * </dl>
             * @preventable _defDataFn
             */
            this.publish("data", {defaultFn: Y.bind("_defDataFn", this), queuable:true});

            /**
             * Fired when response is returned.
             *
             * @event response
             * @param e {Event.Facade} Event Facade with the following properties:
             * <dl>
             * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
             * <dt>request (Object)</dt> <dd>The request.</dd>
             * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
             *     <dl>
             *         <dt>success (Function)</dt> <dd>Success handler.</dd>
             *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
             *     </dl>
             * </dd>
             * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
             * <dt>data (Object)</dt> <dd>Raw data.</dd>
             * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
             *     <dl>
             *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
             *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
             *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
             *     </dl>
             * </dd>
             * </dl>
             * @preventable _defResponseFn
             */
             this.publish("response", {defaultFn: Y.bind("_defResponseFn", this), queuable:true});

            /**
             * Fired when an error is encountered.
             *
             * @event error
             * @param e {Event.Facade} Event Facade with the following properties:
             * <dl>
             * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
             * <dt>request (Object)</dt> <dd>The request.</dd>
             * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
             *     <dl>
             *         <dt>success (Function)</dt> <dd>Success handler.</dd>
             *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
             *     </dl>
             * </dd>
             * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
             * <dt>data (Object)</dt> <dd>Raw data.</dd>
             * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
             *     <dl>
             *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
             *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
             *         <dt>error (Object)</dt> <dd>Error object.</dd>
             *     </dl>
             * </dd>
             * </dl>
             */

        },

        /**
         * Manages request/response transaction. Must fire <code>response</code>
         * event when response is received. This method should be implemented by
         * subclasses to achieve more complex behavior such as accessing remote data.
         *
         * @method _defRequestFn
         * @param e {Event.Facade} Event Facadewith the following properties:
         * <dl>
         * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
         * <dt>request (Object)</dt> <dd>The request.</dd>
         * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
         *     <dl>
         *         <dt>success (Function)</dt> <dd>Success handler.</dd>
         *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
         *     </dl>
         * </dd>
         * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
         * </dl>
         * @protected
         */
        _defRequestFn: function(e) {
            var data = this.get("source");

            // Problematic data
            if(LANG.isUndefined(data)) {
                e.error = new Error("Local source undefined");
            }
            if(e.error) {
                this.fire("error", e);
                Y.log("Error in response", "error", "datasource-local");
            }

            this.fire("data", Y.mix({data:data}, e));
            Y.log("Transaction " + e.tId + " complete. Request: " +
                    Y.dump(e.request) + " . Response: " + Y.dump(e.response), "info", "datasource-local");
        },

        /**
         * Normalizes raw data into a response that includes results and meta properties.
         *
         * @method _defDataFn
         * @param e {Event.Facade} Event Facade with the following properties:
         * <dl>
         * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
         * <dt>request (Object)</dt> <dd>The request.</dd>
         * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
         *     <dl>
         *         <dt>success (Function)</dt> <dd>Success handler.</dd>
         *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
         *     </dl>
         * </dd>
         * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
         * <dt>data (Object)</dt> <dd>Raw data.</dd>
         * </dl>
         * @protected
         */
        _defDataFn: function(e) {
            var data = e.data,
                meta = e.meta,
                response = {
                    results: (LANG.isArray(data)) ? data : [data],
                    meta: (meta) ? meta : {}
                };

            this.fire("response", Y.mix({response: response}, e));
        },

        /**
         * Sends data as a normalized response to callback.
         *
         * @method _defResponseFn
         * @param e {Event.Facade} Event Facade with the following properties:
         * <dl>
         * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
         * <dt>request (Object)</dt> <dd>The request.</dd>
         * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
         *     <dl>
         *         <dt>success (Function)</dt> <dd>Success handler.</dd>
         *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
         *     </dl>
         * </dd>
         * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
         * <dt>data (Object)</dt> <dd>Raw data.</dd>
         * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
         *     <dl>
         *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
         *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
         *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
         *     </dl>
         * </dd>
         * </dl>
         * @protected
         */
        _defResponseFn: function(e) {
            // Send the response back to the callback
            DSLocal.issueCallback(e);
        },

        /**
         * Generates a unique transaction ID and fires <code>request</code> event.
         *
         * @method sendRequest
         * @param request {Object} Request.
         * @param callback {Object} An object literal with the following properties:
         *     <dl>
         *     <dt><code>success</code></dt>
         *     <dd>The function to call when the data is ready.</dd>
         *     <dt><code>failure</code></dt>
         *     <dd>The function to call upon a response failure condition.</dd>
         *     <dt><code>argument</code></dt>
         *     <dd>Arbitrary data payload that will be passed back to the success and failure handlers.</dd>
         *     </dl>
         * @param cfg {Object} Configuration object
         * @return {Number} Transaction ID.
         */
        sendRequest: function(request, callback, cfg) {
            var tId = DSLocal._tId++;
            this.fire("request", {tId:tId, request:request, callback:callback, cfg:cfg || {}});
            Y.log("Transaction " + tId + " sent request: " + Y.dump(request), "info", "datasource-local");
            return tId;
        }
    });

    Y.namespace("DataSource").Local = DSLocal;

Copyright © 2009 Yahoo! Inc. All rights reserved.