build/jsonp/jsonp.js

	jsonp.js revision afd6c54b4b2a0eb021233651a894e5a3ce3f1ca4
c94489fa397a00c551bc087b783123fde4efb904Dav GlassYUI.add('jsonp-base', function(Y) {
c94489fa397a00c551bc087b783123fde4efb904Dav Glass
fc67d6c0ec40e25fd6756153861ebdb65e577014Dav Glassvar isFunction = Y.Lang.isFunction;
fc67d6c0ec40e25fd6756153861ebdb65e577014Dav Glass
748017e442bd0838f8ff8cf53f67e6aaf31484e1Dav Glass/**
fc67d6c0ec40e25fd6756153861ebdb65e577014Dav Glass * <p>Provides a JSONPRequest class for repeated JSONP calls, and a convenience
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * method Y.jsonp(url, callback) to instantiate and send a JSONP request.</p>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * <p>Both the constructor as well as the convenience function take two
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * parameters: a url string and a callback.</p>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * <p>The url provided must include the placeholder string
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * &quot;{callback}&quot; which will be replaced by a dynamically
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * generated routing function to pass the data to your callback function.
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * An example url might look like
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * &quot;http://example.com/service?callback={callback}&quot;.</p>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * <p>The second parameter can be a callback function that accepts the JSON
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * payload as its argument, or a configuration object supporting the keys:</p>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * <ul>
3be83a94a2eca59b109251c4b7c99b99af927f82Dav Glass *   <li>on - map of callback subscribers
0db84e0da684308b0fd9ea9b5906c11bafa7a246Dav Glass *      <ul>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *         <li>success - function handler for successful transmission</li>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *         <li>failure - function handler for failed transmission</li>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *         <li>timeout - function handler for transactions that timeout</li>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *      </ul>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *  </li>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *  <li>format  - override function for inserting the proxy name in the url</li>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *  <li>timeout - the number of milliseconds to wait before giving up</li>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *  <li>context - becomes <code>this</code> in the callbacks</li>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *  <li>args    - array of subsequent parameters to pass to the callbacks</li>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * </ul>
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass *
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * @module jsonp
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * @submodule jsonp-base
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * @class JSONPRequest
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * @constructor
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * @param url {String} the url of the JSONP service
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass * @param callback {Object|Function} the default callback configuration or
748017e442bd0838f8ff8cf53f67e6aaf31484e1Dav Glass *                                   success handler
748017e442bd0838f8ff8cf53f67e6aaf31484e1Dav Glass */
748017e442bd0838f8ff8cf53f67e6aaf31484e1Dav Glassfunction JSONPRequest() {
748017e442bd0838f8ff8cf53f67e6aaf31484e1Dav Glass    this._init.apply(this, arguments);
748017e442bd0838f8ff8cf53f67e6aaf31484e1Dav Glass}
a2621d519886de7d60c30c5a0850f5c17fd2fb36Dav Glass
a2621d519886de7d60c30c5a0850f5c17fd2fb36Dav GlassJSONPRequest.prototype = {
3be83a94a2eca59b109251c4b7c99b99af927f82Dav Glass    /**
a2621d519886de7d60c30c5a0850f5c17fd2fb36Dav Glass     * Set up the success and failure handlers and the regex pattern used
a2621d519886de7d60c30c5a0850f5c17fd2fb36Dav Glass     * to insert the temporary callback name in the url.
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     *
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     * @method _init
fec0b12eb7538bebc558c3efe1c7f31e295cdc82Dav Glass     * @param url {String} the url of the JSONP service
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     * @param callback {Object|Function} Optional success callback or config
d2a5a45ff58ab15a8ee0339edcd03f0243373d59Dav Glass     *                  object containing success and failure functions and
0db84e0da684308b0fd9ea9b5906c11bafa7a246Dav Glass     *                  the url regex.
0db84e0da684308b0fd9ea9b5906c11bafa7a246Dav Glass     * @protected
fec0b12eb7538bebc558c3efe1c7f31e295cdc82Dav Glass     */
0db84e0da684308b0fd9ea9b5906c11bafa7a246Dav Glass    _init : function (url, callback) {
0db84e0da684308b0fd9ea9b5906c11bafa7a246Dav Glass        this.url = url;
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass        // Accept a function, an object, or nothing
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass        callback = (isFunction(callback)) ?
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass            { on: { success: callback } } :
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass            callback || {};
100b8bd9adaf6900bd0dfb6083a8a788ca8cf23cDav Glass
c94489fa397a00c551bc087b783123fde4efb904Dav Glass        var subs = callback.on || {};
c94489fa397a00c551bc087b783123fde4efb904Dav Glass
c94489fa397a00c551bc087b783123fde4efb904Dav Glass        if (!subs.success) {
            subs.success = this._defaultCallback(url, callback);
        }

        // Apply defaults and store
        this._config = Y.merge({
                context: this,
                args   : [],
                format : this._format
            }, callback, { on: subs });
    },

    /**
     * Override this method to provide logic to default the success callback if
     * it is not provided at construction.  This is overridden by jsonp-url to
     * parse the callback from the url string.
     *
     * @method _defaultCallback
     * @param url {String} the url passed at construction
     * @param config {Object} (optional) the config object passed at
     *                        construction
     * @return {Function}
     */
    _defaultCallback: function () {},

    /**
     * Issues the JSONP request.
     *
     * @method send
     * @chainable
     */
    send : function () {
        var proxy  = Y.guid(),
            config = this._config,
            url    = config.format.call(this,
                        this.url, 'YUI.Env.JSONP.' + proxy);

        if (!config.on.success) {
            return this;
        }

        function wrap(fn) {
            return (isFunction(fn)) ?
                function (data) {
                    delete YUI.Env.JSONP[proxy];
                    fn.apply(config.context, [data].concat(config.args));
                } :
                null;
        }

        // Temporary un-sandboxed function alias
        // TODO: queuing
        YUI.Env.JSONP[proxy] = wrap(config.on.success);

        Y.Get.script(url, {
            onFailure: wrap(config.on.failure),
            onTimeout: wrap(config.on.timeout),
            timeout  : config.timeout
        });

        return this;
    },

    /**
     * Initiates the JSONP transaction.
     *
     * @method _dispatch
     * @param url {String} fully formed url with callback
     * @param config {Object} configuration object
     * @protected
     */
    _dispatch: function (url, config) {
    },

    /**
     * Default url formatter.  Looks for callback= in the url and appends it
     * if not present.  The supplied proxy name will be assigned to the query
     * param.  Override this method by passing a function as the
     * &quot;format&quot; property in the config object to the constructor.
     *
     * @method _format
     * @param url { String } the original url
     * @param proxy {String} the function name that will be used as a proxy to
     *      the configured callback methods.
     * @return {String} fully qualified JSONP url
     * @protected
     */
    _format: function (url, proxy) {
        return url.replace(/\{callback\}/, proxy);
    }
};

Y.JSONPRequest = JSONPRequest;

/**
 *
 * @method Y.jsonp
 * @param url {String} the url of the JSONP service with the {callback}
 *          placeholder where the callback function name typically goes.
 * @param c {Function|Object} Callback function accepting the JSON payload
 *          as its argument, or a configuration object (see above).
 * @return {JSONPRequest}
 * @static
 */
Y.jsonp = function (url,c) {
    return new Y.JSONPRequest(url,c).send();
};

YUI.Env.JSONP = {};


}, '@VERSION@' ,{requires:['get','oop']});
YUI.add('jsonp-url', function(Y) {

var JSONPRequest = Y.JSONPRequest,
    getByPath    = Y.Object.getValue,
    noop         = function () {},
    DOT = '.',
    AT  = '@';

/**
 * Adds support for parsing complex callback identifiers from the jsonp url.
 * This includes callback=foo[1]bar.baz["goo"] as well as referencing methods
 * in the YUI instance.
 *
 * @module jsonp
 * @submodule jsonp-url
 * @for JSONPRequest
 */

Y.mix(JSONPRequest.prototype, {
    /**
     * RegExp used by the default URL formatter to insert the generated callback
     * name into the JSONP url.  Looks for a query param callback=.  If a value
     * is assigned, it will be clobbered.
     *
     * @member _pattern
     * @type RegExp
     * @default /\bcallback=.*?(?=&|$)/i
     * @protected
     */
    _pattern: /\bcallback=(.*?)(?=&|$)/i,

    /**
     * Template used by the default URL formatter to add the callback function
     * name to the url.
     *
     * @member _template
     * @type String
     * @default "callback={callback}"
     * @protected
     */
    _template: "callback={callback}",

    /**
     * <p>Parses the url for a callback named explicitly in the string.
     * Override this if the target JSONP service uses a different query
     * parameter or url format.</p>
     *
     * <p>If the callback is declared inline, the corresponding function will
     * be returned.  Otherwise null.</p>
     *
     * @method _defaultCallback
     * @param url {String} the url to search in
     * @return {Function} the callback function if found, or null
     * @protected
     */
    _defaultCallback: function (url) {
        var match = url.match(this._pattern),
            bracketAlias = {},
            i = 0,
            path, callback;

        if (match) {
            // callback=foo[2].bar["baz"]func => ['foo','2','bar','baz','func']
            // TODO: Doesn't handle escaping or url encoding
            path = match[1].replace(/\[(?:(['"])([^\]\1]+)\1|(\d+))\]/g,
                        function (_, quote, name, idx) {
                            var nextChar = (RegExp.rightContext||'.').charAt(0),
                                token = AT + (++i);

                            bracketAlias[token] = name || idx;

                            if (nextChar !== DOT && nextChar !== '[') {
                                token += DOT;
                            }
                            return DOT + token;
                        }).split(/\./);

            // Restore tokens from brack notation
            Y.each(path, function (bit, i) {
                if (bit.charAt(0) === '@') {
                    path[i] = bracketAlias[bit];
                }
            });

            // First look for a global function, then the Y, then try the Y
            // again from the second token (to support "...?callback=Y.handler")
            callback = getByPath(Y.config.win, path) ||
                       getByPath(Y, path) ||
                       getByPath(Y, path.slice(1));
        }

        return callback || noop;
    },

    /**
     * URL formatter that looks for callback= in the url and appends it
     * if not present.  The supplied proxy name will be assigned to the query
     * param.  Override this method by passing a function as the
     * &quot;format&quot; property in the config object to the constructor.
     *
     * @method _format
     * @param url { String } the original url
     * @param proxy {String} the function name that will be used as a proxy to
     *      the configured callback methods.
     * @return {String} fully qualified JSONP url
     * @protected
     */
    _format: function (url, proxy) {
        var callback = this._template.replace(/\{callback\}/, proxy),
            lastChar;

        if (this._pattern.test(url)) {
            return url.replace(this._pattern, callback);
        } else {
            lastChar = url.slice(-1);
            if (lastChar !== '&' && lastChar !== '?') {
                url += (url.indexOf('?') > -1) ? '&' : '?';
            }
            return url + callback;
        }
    }

}, true);


}, '@VERSION@' ,{requires:['jsonp-base']});


YUI.add('jsonp', function(Y){}, '@VERSION@' ,{use:['jsonp-base', 'jsonp-url']});