yql/js/yql.js

	yql.js revision 09547accdabd440af5613767ba0eda138a7f1ffc
4d6c3c157705c101f044293dd642b62683918dedDav Glass    /**
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * This class adds a sugar class to allow access to YQL (http://developer.yahoo.com/yql/).
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @module yql
4d6c3c157705c101f044293dd642b62683918dedDav Glass     */
4d6c3c157705c101f044293dd642b62683918dedDav Glass    /**
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * Utility Class used under the hood my the YQL class
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @class YQLRequest
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @constructor
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @param {String} sql The SQL statement to execute
e185b559bf5512df7169f7901db9b2ec3771260bDav Glass     * @param {Function/Object} callback The callback to execute after the query (Falls through to JSONP).
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @param {Object} params An object literal of extra parameters to pass along (optional).
7368220dd87582da2552f8152bbff2508e5ddf1dDav Glass     * @param {Object} opts An object literal of configuration options (optional): proto (http|https), base (url)
4d6c3c157705c101f044293dd642b62683918dedDav Glass     */
e185b559bf5512df7169f7901db9b2ec3771260bDav Glass    var YQLRequest = function (sql, callback, params, opts) {
4d6c3c157705c101f044293dd642b62683918dedDav Glass
4d6c3c157705c101f044293dd642b62683918dedDav Glass        if (!params) {
4d6c3c157705c101f044293dd642b62683918dedDav Glass            params = {};
4d6c3c157705c101f044293dd642b62683918dedDav Glass        }
4d6c3c157705c101f044293dd642b62683918dedDav Glass        params.q = sql;
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass        //Allow format override.. JSON-P-X
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass        if (!params.format) {
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass            params.format = Y.YQLRequest.FORMAT;
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass        }
4d6c3c157705c101f044293dd642b62683918dedDav Glass        if (!params.env) {
4d6c3c157705c101f044293dd642b62683918dedDav Glass            params.env = Y.YQLRequest.ENV;
4d6c3c157705c101f044293dd642b62683918dedDav Glass        }
4d6c3c157705c101f044293dd642b62683918dedDav Glass
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        this._params = params;
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        this._opts = opts;
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        this._callback = callback;
4d6c3c157705c101f044293dd642b62683918dedDav Glass
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass    };
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass    YQLRequest.prototype = {
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass        /**
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass        * @private
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass        * @property _jsonp
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass        * @description Reference to the JSONP instance used to make the queries
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass        */
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass        _jsonp: null,
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        /**
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @private
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @property _opts
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @description Holder for the opts argument
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        */
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        _opts: null,
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        /**
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @private
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @property _callback
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @description Holder for the callback argument
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        */
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        _callback: null,
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        /**
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @private
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @property _params
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @description Holder for the params argument
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        */
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        _params: null,
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        /**
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @method send
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @description The method that executes the YQL Request.
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @chainable
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        * @returns {YQLRequest}
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        */
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        send: function() {
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass            var qs = '', url = ((this._opts && this._opts.proto) ? this._opts.proto : Y.YQLRequest.PROTO);
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass            Y.each(this._params, function(v, k) {
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass                qs += k + '=' + encodeURIComponent(v) + '&';
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass            });
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass            url += ((this._opts && this._opts.base) ? this._opts.base : Y.YQLRequest.BASE_URL) + qs;
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass            var o = (!Y.Lang.isFunction(this._callback)) ? this._callback : { on: { success: this._callback } };
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass            if (o.allowCache !== false) {
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass                o.allowCache = true;
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass            }
09547accdabd440af5613767ba0eda138a7f1ffcDav Glass
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass            if (!this._jsonp) {
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass                this._jsonp = Y.jsonp(url, o);
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass            } else {
09547accdabd440af5613767ba0eda138a7f1ffcDav Glass                this._jsonp.url = url;
09547accdabd440af5613767ba0eda138a7f1ffcDav Glass                if (o.on && o.on.success) {
09547accdabd440af5613767ba0eda138a7f1ffcDav Glass                    this._jsonp._config.on.success = o.on.success;
09547accdabd440af5613767ba0eda138a7f1ffcDav Glass                }
09547accdabd440af5613767ba0eda138a7f1ffcDav Glass                this._jsonp.send();
9ce5c4aa30657fb7e4ef73dca0ab98c7a42d4cd4Dav Glass            }
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass            return this;
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        }
4d6c3c157705c101f044293dd642b62683918dedDav Glass    };
4d6c3c157705c101f044293dd642b62683918dedDav Glass
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass    /**
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass    * @static
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass    * @property FORMAT
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass    * @description Default format to use: json
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass    */
fb1acfadd2c965ce38a6caa9cfa16e051ab70702Dav Glass    YQLRequest.FORMAT = 'json';
4d6c3c157705c101f044293dd642b62683918dedDav Glass    /**
4d6c3c157705c101f044293dd642b62683918dedDav Glass    * @static
4d6c3c157705c101f044293dd642b62683918dedDav Glass    * @property PROTO
4d6c3c157705c101f044293dd642b62683918dedDav Glass    * @description Default protocol to use: http
4d6c3c157705c101f044293dd642b62683918dedDav Glass    */
e185b559bf5512df7169f7901db9b2ec3771260bDav Glass    YQLRequest.PROTO = 'http';
4d6c3c157705c101f044293dd642b62683918dedDav Glass    /**
4d6c3c157705c101f044293dd642b62683918dedDav Glass    * @static
4d6c3c157705c101f044293dd642b62683918dedDav Glass    * @property BASE_URL
4d6c3c157705c101f044293dd642b62683918dedDav Glass    * @description The base URL to query: query.yahooapis.com/v1/public/yql?
4d6c3c157705c101f044293dd642b62683918dedDav Glass    */
e185b559bf5512df7169f7901db9b2ec3771260bDav Glass    YQLRequest.BASE_URL = ':/'+'/query.yahooapis.com/v1/public/yql?';
4d6c3c157705c101f044293dd642b62683918dedDav Glass    /**
4d6c3c157705c101f044293dd642b62683918dedDav Glass    * @static
4d6c3c157705c101f044293dd642b62683918dedDav Glass    * @property ENV
4d6c3c157705c101f044293dd642b62683918dedDav Glass    * @description The environment file to load: http://datatables.org/alltables.env
4d6c3c157705c101f044293dd642b62683918dedDav Glass    */
e185b559bf5512df7169f7901db9b2ec3771260bDav Glass    YQLRequest.ENV = 'http:/'+'/datatables.org/alltables.env';
4d6c3c157705c101f044293dd642b62683918dedDav Glass
e185b559bf5512df7169f7901db9b2ec3771260bDav Glass    Y.YQLRequest = YQLRequest;
4d6c3c157705c101f044293dd642b62683918dedDav Glass
4d6c3c157705c101f044293dd642b62683918dedDav Glass    /**
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * This class adds a sugar class to allow access to YQL (http://developer.yahoo.com/yql/).
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @class YQL
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @constructor
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @param {String} sql The SQL statement to execute
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @param {Function} callback The callback to execute after the query (optional).
4d6c3c157705c101f044293dd642b62683918dedDav Glass     * @param {Object} params An object literal of extra parameters to pass along (optional).
4d6c3c157705c101f044293dd642b62683918dedDav Glass     */
4d6c3c157705c101f044293dd642b62683918dedDav Glass    Y.YQL = function(sql, callback, params) {
11173168fe9e382ff5a815fcf26d1686a0065c64Dav Glass        return new Y.YQLRequest(sql, callback, params).send();
4d6c3c157705c101f044293dd642b62683918dedDav Glass    };
4d6c3c157705c101f044293dd642b62683918dedDav Glass