#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# File: autocomplete/js/autocomplete-sources.js

    /**
    Mixes support for JSONP and YQL result sources into AutoCompleteBase.

    @module autocomplete
    @submodule autocomplete-sources
    **/

    var ACBase = Y.AutoCompleteBase,
        Lang   = Y.Lang,

        _SOURCE_SUCCESS = '_sourceSuccess',

        MAX_RESULTS         = 'maxResults',
        REQUEST_TEMPLATE    = 'requestTemplate',
        RESULT_LIST_LOCATOR = 'resultListLocator';

    // Add prototype properties and methods to AutoCompleteBase.
    Y.mix(ACBase.prototype, {
        /**
        Regular expression used to determine whether a String source is a YQL query.

        @property _YQL_SOURCE_REGEX
        @type RegExp
        @protected
        @for AutoCompleteBase
        **/
        _YQL_SOURCE_REGEX: /^(?:select|set|use)\s+/i,

        /**
        Runs before AutoCompleteBase's `_createObjectSource()` method and augments
        it to support additional object-based source types.

        @method _beforeCreateObjectSource
        @param {String} source
        @protected
        @for AutoCompleteBase
        **/
        _beforeCreateObjectSource: function (source) {
            // If the object is a <select> node, use the options as the result
            // source.
            if (source instanceof Y.Node &&
                    source.get('nodeName').toLowerCase() === 'select') {

                return this._createSelectSource(source);
            }

            // If the object is a JSONPRequest instance, try to use it as a JSONP
            // source.
            if (Y.JSONPRequest && source instanceof Y.JSONPRequest) {
                return this._createJSONPSource(source);
            }

            // Fall back to a basic object source.
            return this._createObjectSource(source);
        },

        /**
        Creates a DataSource-like object that uses `Y.io` as a source. See the
        `source` attribute for more details.

        @method _createIOSource
        @param {String} source URL.
        @return {Object} DataSource-like object.
        @protected
        @for AutoCompleteBase
        **/
        _createIOSource: function (source) {
            var ioSource = {type: 'io'},
                that     = this,
                ioRequest, lastRequest, loading;

            // Private internal _sendRequest method that will be assigned to
            // ioSource.sendRequest once io-base and json-parse are available.
            function _sendRequest(request) {
                var cacheKey = request.request;

                // Return immediately on a cached response.
                if (that._cache && cacheKey in that._cache) {
                    that[_SOURCE_SUCCESS](that._cache[cacheKey], request);
                    return;
                }

                // Cancel any outstanding requests.
                if (ioRequest && ioRequest.isInProgress()) {
                    ioRequest.abort();
                }

                ioRequest = Y.io(that._getXHRUrl(source, request), {
                    on: {
                        success: function (tid, response) {
                            var data;

                            try {
                                data = Y.JSON.parse(response.responseText);
                            } catch (ex) {
                                Y.error('JSON parse error', ex);
                            }

                            if (data) {
                                that._cache && (that._cache[cacheKey] = data);
                                that[_SOURCE_SUCCESS](data, request);
                            }
                        }
                    }
                });
            }

            ioSource.sendRequest = function (request) {
                // Keep track of the most recent request in case there are multiple
                // requests while we're waiting for the IO module to load. Only the
                // most recent request will be sent.
                lastRequest = request;

                if (loading) { return; }

                loading = true;

                // Lazy-load the io-base and json-parse modules if necessary,
                // then overwrite the sendRequest method to bypass this check in
                // the future.
                Y.use('io-base', 'json-parse', function () {
                    ioSource.sendRequest = _sendRequest;
                    _sendRequest(lastRequest);
                });
            };

            return ioSource;
        },

        /**
        Creates a DataSource-like object that uses the specified JSONPRequest
        instance as a source. See the `source` attribute for more details.

        @method _createJSONPSource
        @param {JSONPRequest|String} source URL string or JSONPRequest instance.
        @return {Object} DataSource-like object.
        @protected
        @for AutoCompleteBase
        **/
        _createJSONPSource: function (source) {
            var jsonpSource = {type: 'jsonp'},
                that        = this,
                lastRequest, loading;

            function _sendRequest(request) {
                var cacheKey = request.request,
                    query    = request.query;

                if (that._cache && cacheKey in that._cache) {
                    that[_SOURCE_SUCCESS](that._cache[cacheKey], request);
                    return;
                }

                // Hack alert: JSONPRequest currently doesn't support
                // per-request callbacks, so we're reaching into the protected
                // _config object to make it happen.
                //
                // This limitation is mentioned in the following JSONP
                // enhancement ticket:
                //
                // http://yuilibrary.com/projects/yui3/ticket/2529371
                source._config.on.success = function (data) {
                    that._cache && (that._cache[cacheKey] = data);
                    that[_SOURCE_SUCCESS](data, request);
                };

                source.send(query);
            }

            jsonpSource.sendRequest = function (request) {
                // Keep track of the most recent request in case there are multiple
                // requests while we're waiting for the JSONP module to load. Only
                // the most recent request will be sent.
                lastRequest = request;

                if (loading) { return; }

                loading = true;

                // Lazy-load the JSONP module if necessary, then overwrite the
                // sendRequest method to bypass this check in the future.
                Y.use('jsonp', function () {
                    // Turn the source into a JSONPRequest instance if it isn't
                    // one already.
                    if (!(source instanceof Y.JSONPRequest)) {
                        source = new Y.JSONPRequest(source, {
                            format: Y.bind(that._jsonpFormatter, that)
                        });
                    }

                    jsonpSource.sendRequest = _sendRequest;
                    _sendRequest(lastRequest);
                });
            };

            return jsonpSource;
        },

        /**
        Creates a DataSource-like object that uses the specified `<select>` node as
        a source.

        @method _createSelectSource
        @param {Node} source YUI Node instance wrapping a `<select>` node.
        @return {Object} DataSource-like object.
        @protected
        @for AutoCompleteBase
        **/
        _createSelectSource: function (source) {
            var that = this;

            return {
                type: 'select',
                sendRequest: function (request) {
                    var options = [];

                    source.get('options').each(function (option) {
                        options.push({
                            html    : option.get('innerHTML'),
                            index   : option.get('index'),
                            node    : option,
                            selected: option.get('selected'),
                            text    : option.get('text'),
                            value   : option.get('value')
                        });
                    });

                    that[_SOURCE_SUCCESS](options, request);
                }
            };
        },

        /**
        Creates a DataSource-like object that calls the specified  URL or executes
        the specified YQL query for results. If the string starts with "select ",
        "use ", or "set " (case-insensitive), it's assumed to be a YQL query;
        otherwise, it's assumed to be a URL (which may be absolute or relative).
        URLs containing a "{callback}" placeholder are assumed to be JSONP URLs; all
        others will use XHR. See the `source` attribute for more details.

        @method _createStringSource
        @param {String} source URL or YQL query.
        @return {Object} DataSource-like object.
        @protected
        @for AutoCompleteBase
        **/
        _createStringSource: function (source) {
            if (this._YQL_SOURCE_REGEX.test(source)) {
                // Looks like a YQL query.
                return this._createYQLSource(source);
            } else if (source.indexOf('{callback}') !== -1) {
                // Contains a {callback} param and isn't a YQL query, so it must be
                // JSONP.
                return this._createJSONPSource(source);
            } else {
                // Not a YQL query or JSONP, so we'll assume it's an XHR URL.
                return this._createIOSource(source);
            }
        },

        /**
        Creates a DataSource-like object that uses the specified YQL query string to
        create a YQL-based source. See the `source` attribute for details. If no
        `resultListLocator` is defined, this method will set a best-guess locator
        that might work for many typical YQL queries.

        @method _createYQLSource
        @param {String} source YQL query.
        @return {Object} DataSource-like object.
        @protected
        @for AutoCompleteBase
        **/
        _createYQLSource: function (source) {
            var that      = this,
                yqlSource = {type: 'yql'},
                lastRequest, loading, yqlRequest;

            if (!that.get(RESULT_LIST_LOCATOR)) {
                that.set(RESULT_LIST_LOCATOR, that._defaultYQLLocator);
            }

            function _sendRequest(request) {
                var query      = request.query,
                    env        = that.get('yqlEnv'),
                    maxResults = that.get(MAX_RESULTS),
                    callback, opts, yqlQuery;

                yqlQuery = Lang.sub(source, {
                    maxResults: maxResults > 0 ? maxResults : 1000,
                    request   : request.request,
                    query     : query
                });

                if (that._cache && yqlQuery in that._cache) {
                    that[_SOURCE_SUCCESS](that._cache[yqlQuery], request);
                    return;
                }

                callback = function (data) {
                    that._cache && (that._cache[yqlQuery] = data);
                    that[_SOURCE_SUCCESS](data, request);
                };

                opts = {proto: that.get('yqlProtocol')};

                // Only create a new YQLRequest instance if this is the
                // first request. For subsequent requests, we'll reuse the
                // original instance.
                if (yqlRequest) {
                    yqlRequest._callback   = callback;
                    yqlRequest._opts       = opts;
                    yqlRequest._params.q   = yqlQuery;

                    if (env) {
                        yqlRequest._params.env = env;
                    }
                } else {
                    yqlRequest = new Y.YQLRequest(yqlQuery, {
                        on: {success: callback},
                        allowCache: false // temp workaround until JSONP has per-URL callback proxies
                    }, env ? {env: env} : null, opts);
                }

                yqlRequest.send();
            }

            yqlSource.sendRequest = function (request) {
                // Keep track of the most recent request in case there are multiple
                // requests while we're waiting for the YQL module to load. Only the
                // most recent request will be sent.
                lastRequest = request;

                if (!loading) {
                    // Lazy-load the YQL module if necessary, then overwrite the
                    // sendRequest method to bypass this check in the future.
                    loading = true;

                    Y.use('yql', function () {
                        yqlSource.sendRequest = _sendRequest;
                        _sendRequest(lastRequest);
                    });
                }
            };

            return yqlSource;
        },

        /**
        Default resultListLocator used when a string-based YQL source is set and the
        implementer hasn't already specified one.

        @method _defaultYQLLocator
        @param {Object} response YQL response object.
        @return {Array}
        @protected
        @for AutoCompleteBase
        **/
        _defaultYQLLocator: function (response) {
            var results = response && response.query && response.query.results,
                values;

            if (results && Lang.isObject(results)) {
                // If there's only a single value on YQL's results object, that
                // value almost certainly contains the array of results we want. If
                // there are 0 or 2+ values, then the values themselves are most
                // likely the results we want.
                values  = Y.Object.values(results) || [];
                results = values.length === 1 ? values[0] : values;

                if (!Lang.isArray(results)) {
                    results = [results];
                }
            } else {
                results = [];
            }

            return results;
        },

        /**
        Returns a formatted XHR URL based on the specified base _url_, _query_, and
        the current _requestTemplate_ if any.

        @method _getXHRUrl
        @param {String} url Base URL.
        @param {Object} request Request object containing `query` and `request`
          properties.
        @return {String} Formatted URL.
        @protected
        @for AutoCompleteBase
        **/
        _getXHRUrl: function (url, request) {
            var maxResults = this.get(MAX_RESULTS);

            if (request.query !== request.request) {
                // Append the request template to the URL.
                url += request.request;
            }

            return Lang.sub(url, {
                maxResults: maxResults > 0 ? maxResults : 1000,
                query     : encodeURIComponent(request.query)
            });
        },

        /**
        URL formatter passed to `JSONPRequest` instances.

        @method _jsonpFormatter
        @param {String} url
        @param {String} proxy
        @param {String} query
        @return {String} Formatted URL
        @protected
        @for AutoCompleteBase
        **/
        _jsonpFormatter: function (url, proxy, query) {
            var maxResults      = this.get(MAX_RESULTS),
                requestTemplate = this.get(REQUEST_TEMPLATE);

            if (requestTemplate) {
                url += requestTemplate(query);
            }

            return Lang.sub(url, {
                callback  : proxy,
                maxResults: maxResults > 0 ? maxResults : 1000,
                query     : encodeURIComponent(query)
            });
        }
    });

    // Add attributes to AutoCompleteBase.
    Y.mix(ACBase.ATTRS, {
        /**
        YQL environment file URL to load when the `source` is set to a YQL query.
        Set this to `null` to use the default Open Data Tables environment file
        (http://datatables.org/alltables.env).

        @attribute yqlEnv
        @type String
        @default null
        @for AutoCompleteBase
        **/
        yqlEnv: {
            value: null
        },

        /**
        URL protocol to use when the `source` is set to a YQL query.

        @attribute yqlProtocol
        @type String
        @default 'http'
        @for AutoCompleteBase
        **/
        yqlProtocol: {
            value: 'http'
        }
    });

    // Tell AutoCompleteBase about the new source types it can now support.
    Y.mix(ACBase.SOURCE_TYPES, {
        io    : '_createIOSource',
        jsonp : '_createJSONPSource',
        object: '_beforeCreateObjectSource', // Run our version before the base version.
        select: '_createSelectSource',
        string: '_createStringSource',
        yql   : '_createYQLSource'
    }, true);