1 /*

     2 YUI 3.10.3 (build 2fb5187)

     3 Copyright 2013 Yahoo! Inc. All rights reserved.

     4 Licensed under the BSD License.

     5 http://yuilibrary.com/license/

     6 */

     7 

     8 YUI.add('autocomplete-base', function (Y, NAME) {

     9 

    10 /**

    11 Provides automatic input completion or suggestions for text input fields and

    12 textareas.

    13 

    14 @module autocomplete

    15 @main autocomplete

    16 @since 3.3.0

    17 **/

    18 

    19 /**

    20 `Y.Base` extension that provides core autocomplete logic (but no UI

    21 implementation) for a text input field or textarea. Must be mixed into a

    22 `Y.Base`-derived class to be useful.

    23 

    24 @module autocomplete

    25 @submodule autocomplete-base

    26 **/

    27 

    28 /**

    29 Extension that provides core autocomplete logic (but no UI implementation) for a

    30 text input field or textarea.

    31 

    32 The `AutoCompleteBase` class provides events and attributes that abstract away

    33 core autocomplete logic and configuration, but does not provide a widget

    34 implementation or suggestion UI. For a prepackaged autocomplete widget, see

    35 `AutoCompleteList`.

    36 

    37 This extension cannot be instantiated directly, since it doesn't provide an

    38 actual implementation. It's intended to be mixed into a `Y.Base`-based class or

    39 widget.

    40 

    41 `Y.Widget`-based example:

    42 

    43     YUI().use('autocomplete-base', 'widget', function (Y) {

    44         var MyAC = Y.Base.create('myAC', Y.Widget, [Y.AutoCompleteBase], {

    45             // Custom prototype methods and properties.

    46         }, {

    47             // Custom static methods and properties.

    48         });

    49 

    50         // Custom implementation code.

    51     });

    52 

    53 `Y.Base`-based example:

    54 

    55     YUI().use('autocomplete-base', function (Y) {

    56         var MyAC = Y.Base.create('myAC', Y.Base, [Y.AutoCompleteBase], {

    57             initializer: function () {

    58                 this._bindUIACBase();

    59                 this._syncUIACBase();

    60             },

    61 

    62             // Custom prototype methods and properties.

    63         }, {

    64             // Custom static methods and properties.

    65         });

    66 

    67         // Custom implementation code.

    68     });

    69 

    70 @class AutoCompleteBase

    71 **/

    72 

    73 var Escape  = Y.Escape,

    74     Lang    = Y.Lang,

    75     YArray  = Y.Array,

    76     YObject = Y.Object,

    77 

    78     isFunction = Lang.isFunction,

    79     isString   = Lang.isString,

    80     trim       = Lang.trim,

    81 

    82     INVALID_VALUE = Y.Attribute.INVALID_VALUE,

    83 

    84     _FUNCTION_VALIDATOR = '_functionValidator',

    85     _SOURCE_SUCCESS     = '_sourceSuccess',

    86 

    87     ALLOW_BROWSER_AC    = 'allowBrowserAutocomplete',

    88     INPUT_NODE          = 'inputNode',

    89     QUERY               = 'query',

    90     QUERY_DELIMITER     = 'queryDelimiter',

    91     REQUEST_TEMPLATE    = 'requestTemplate',

    92     RESULTS             = 'results',

    93     RESULT_LIST_LOCATOR = 'resultListLocator',

    94     VALUE               = 'value',

    95     VALUE_CHANGE        = 'valueChange',

    96 

    97     EVT_CLEAR   = 'clear',

    98     EVT_QUERY   = QUERY,

    99     EVT_RESULTS = RESULTS;

   100 

   101 function AutoCompleteBase() {}

   102 

   103 AutoCompleteBase.prototype = {

   104     // -- Lifecycle Methods ----------------------------------------------------

   105     initializer: function () {

   106         // AOP bindings.

   107         Y.before(this._bindUIACBase, this, 'bindUI');

   108         Y.before(this._syncUIACBase, this, 'syncUI');

   109 

   110         // -- Public Events ----------------------------------------------------

   111 

   112         /**

   113         Fires after the query has been completely cleared or no longer meets the

   114         minimum query length requirement.

   115 

   116         @event clear

   117         @param {String} prevVal Value of the query before it was cleared.

   118         @param {String} src Source of the event.

   119         @preventable _defClearFn

   120         **/

   121         this.publish(EVT_CLEAR, {

   122             defaultFn: this._defClearFn

   123         });

   124 

   125         /**

   126         Fires when the contents of the input field have changed and the input

   127         value meets the criteria necessary to generate an autocomplete query.

   128 

   129         @event query

   130         @param {String} inputValue Full contents of the text input field or

   131             textarea that generated the query.

   132         @param {String} query AutoComplete query. This is the string that will

   133             be used to request completion results. It may or may not be the same

   134             as `inputValue`.

   135         @param {String} src Source of the event.

   136         @preventable _defQueryFn

   137         **/

   138         this.publish(EVT_QUERY, {

   139             defaultFn: this._defQueryFn

   140         });

   141 

   142         /**

   143         Fires after query results are received from the source. If no source has

   144         been set, this event will not fire.

   145 

   146         @event results

   147         @param {Array|Object} data Raw, unfiltered result data (if available).

   148         @param {String} query Query that generated these results.

   149         @param {Object[]} results Array of filtered, formatted, and highlighted

   150             results. Each item in the array is an object with the following

   151             properties:

   152 

   153             @param {Node|HTMLElement|String} results.display Formatted result

   154                 HTML suitable for display to the user. If no custom formatter is

   155                 set, this will be an HTML-escaped version of the string in the

   156                 `text` property.

   157             @param {String} [results.highlighted] Highlighted (but not

   158                 formatted) result text. This property will only be set if a

   159                 highlighter is in use.

   160             @param {Any} results.raw Raw, unformatted result in whatever form it

   161                 was provided by the source.

   162             @param {String} results.text Plain text version of the result,

   163                 suitable for being inserted into the value of a text input field

   164                 or textarea when the result is selected by a user. This value is

   165                 not HTML-escaped and should not be inserted into the page using

   166                 `innerHTML` or `Node#setContent()`.

   167 

   168         @preventable _defResultsFn

   169         **/

   170         this.publish(EVT_RESULTS, {

   171             defaultFn: this._defResultsFn

   172         });

   173     },

   174 

   175     destructor: function () {

   176         this._acBaseEvents && this._acBaseEvents.detach();

   177 

   178         delete this._acBaseEvents;

   179         delete this._cache;

   180         delete this._inputNode;

   181         delete this._rawSource;

   182     },

   183 

   184     // -- Public Prototype Methods ---------------------------------------------

   185 

   186     /**

   187     Clears the result cache.

   188 

   189     @method clearCache

   190     @chainable

   191     @since 3.5.0

   192     **/

   193     clearCache: function () {

   194         this._cache && (this._cache = {});

   195         return this;

   196     },

   197 

   198     /**

   199     Sends a request to the configured source. If no source is configured, this

   200     method won't do anything.

   201 

   202     Usually there's no reason to call this method manually; it will be called

   203     automatically when user input causes a `query` event to be fired. The only

   204     time you'll need to call this method manually is if you want to force a

   205     request to be sent when no user input has occurred.

   206 

   207     @method sendRequest

   208     @param {String} [query] Query to send. If specified, the `query` attribute

   209         will be set to this query. If not specified, the current value of the

   210         `query` attribute will be used.

   211     @param {Function} [requestTemplate] Request template function. If not

   212         specified, the current value of the `requestTemplate` attribute will be

   213         used.

   214     @chainable

   215     **/

   216     sendRequest: function (query, requestTemplate) {

   217         var request,

   218             source = this.get('source');

   219 

   220         if (query || query === '') {

   221             this._set(QUERY, query);

   222         } else {

   223             query = this.get(QUERY) || '';

   224         }

   225 

   226         if (source) {

   227             if (!requestTemplate) {

   228                 requestTemplate = this.get(REQUEST_TEMPLATE);

   229             }

   230 

   231             request = requestTemplate ?

   232                 requestTemplate.call(this, query) : query;

   233 

   234             Y.log('sendRequest: ' + request, 'info', 'autocomplete-base');

   235 

   236             source.sendRequest({

   237                 query  : query,

   238                 request: request,

   239 

   240                 callback: {

   241                     success: Y.bind(this._onResponse, this, query)

   242                 }

   243             });

   244         }

   245 

   246         return this;

   247     },

   248 

   249     // -- Protected Lifecycle Methods ------------------------------------------

   250 

   251     /**

   252     Attaches event listeners and behaviors.

   253 

   254     @method _bindUIACBase

   255     @protected

   256     **/

   257     _bindUIACBase: function () {

   258         var inputNode  = this.get(INPUT_NODE),

   259             tokenInput = inputNode && inputNode.tokenInput;

   260 

   261         // If the inputNode has a node-tokeninput plugin attached, bind to the

   262         // plugin's inputNode instead.

   263         if (tokenInput) {

   264             inputNode = tokenInput.get(INPUT_NODE);

   265             this._set('tokenInput', tokenInput);

   266         }

   267 

   268         if (!inputNode) {

   269             Y.error('No inputNode specified.');

   270             return;

   271         }

   272 

   273         this._inputNode = inputNode;

   274 

   275         this._acBaseEvents = new Y.EventHandle([

   276             // This is the valueChange event on the inputNode, provided by the

   277             // event-valuechange module, not our own valueChange.

   278             inputNode.on(VALUE_CHANGE, this._onInputValueChange, this),

   279             inputNode.on('blur', this._onInputBlur, this),

   280 

   281             this.after(ALLOW_BROWSER_AC + 'Change', this._syncBrowserAutocomplete),

   282             this.after('sourceTypeChange', this._afterSourceTypeChange),

   283             this.after(VALUE_CHANGE, this._afterValueChange)

   284         ]);

   285     },

   286 

   287     /**

   288     Synchronizes the UI state of the `inputNode`.

   289 

   290     @method _syncUIACBase

   291     @protected

   292     **/

   293     _syncUIACBase: function () {

   294         this._syncBrowserAutocomplete();

   295         this.set(VALUE, this.get(INPUT_NODE).get(VALUE));

   296     },

   297 

   298     // -- Protected Prototype Methods ------------------------------------------

   299 

   300     /**

   301     Creates a DataSource-like object that simply returns the specified array as

   302     a response. See the `source` attribute for more details.

   303 

   304     @method _createArraySource

   305     @param {Array} source

   306     @return {Object} DataSource-like object.

   307     @protected

   308     **/

   309     _createArraySource: function (source) {

   310         var that = this;

   311 

   312         return {

   313             type: 'array',

   314             sendRequest: function (request) {

   315                 that[_SOURCE_SUCCESS](source.concat(), request);

   316             }

   317         };

   318     },

   319 

   320     /**

   321     Creates a DataSource-like object that passes the query to a custom-defined

   322     function, which is expected to call the provided callback with an array of

   323     results. See the `source` attribute for more details.

   324 

   325     @method _createFunctionSource

   326     @param {Function} source Function that accepts a query and a callback as

   327       parameters, and calls the callback with an array of results.

   328     @return {Object} DataSource-like object.

   329     @protected

   330     **/

   331     _createFunctionSource: function (source) {

   332         var that = this;

   333 

   334         return {

   335             type: 'function',

   336             sendRequest: function (request) {

   337                 var value;

   338 

   339                 function afterResults(results) {

   340                     that[_SOURCE_SUCCESS](results || [], request);

   341                 }

   342 

   343                 // Allow both synchronous and asynchronous functions. If we get

   344                 // a truthy return value, assume the function is synchronous.

   345                 if ((value = source(request.query, afterResults))) {

   346                     afterResults(value);

   347                 }

   348             }

   349         };

   350     },

   351 

   352     /**

   353     Creates a DataSource-like object that looks up queries as properties on the

   354     specified object, and returns the found value (if any) as a response. See

   355     the `source` attribute for more details.

   356 

   357     @method _createObjectSource

   358     @param {Object} source

   359     @return {Object} DataSource-like object.

   360     @protected

   361     **/

   362     _createObjectSource: function (source) {

   363         var that = this;

   364 

   365         return {

   366             type: 'object',

   367             sendRequest: function (request) {

   368                 var query = request.query;

   369 

   370                 that[_SOURCE_SUCCESS](

   371                     YObject.owns(source, query) ? source[query] : [],

   372                     request

   373                 );

   374             }

   375         };

   376     },

   377 

   378     /**

   379     Returns `true` if _value_ is either a function or `null`.

   380 

   381     @method _functionValidator

   382     @param {Function|null} value Value to validate.

   383     @protected

   384     **/

   385     _functionValidator: function (value) {

   386         return value === null || isFunction(value);

   387     },

   388 

   389     /**

   390     Faster and safer alternative to `Y.Object.getValue()`. Doesn't bother

   391     casting the path to an array (since we already know it's an array) and

   392     doesn't throw an error if a value in the middle of the object hierarchy is

   393     neither `undefined` nor an object.

   394 

   395     @method _getObjectValue

   396     @param {Object} obj

   397     @param {Array} path

   398     @return {Any} Located value, or `undefined` if the value was

   399         not found at the specified path.

   400     @protected

   401     **/

   402     _getObjectValue: function (obj, path) {

   403         if (!obj) {

   404             return;

   405         }

   406 

   407         for (var i = 0, len = path.length; obj && i < len; i++) {

   408             obj = obj[path[i]];

   409         }

   410 

   411         return obj;

   412     },

   413 

   414     /**

   415     Parses result responses, performs filtering and highlighting, and fires the

   416     `results` event.

   417 

   418     @method _parseResponse

   419     @param {String} query Query that generated these results.

   420     @param {Object} response Response containing results.

   421     @param {Object} data Raw response data.

   422     @protected

   423     **/

   424     _parseResponse: function (query, response, data) {

   425         var facade = {

   426                 data   : data,

   427                 query  : query,

   428                 results: []

   429             },

   430 

   431             listLocator = this.get(RESULT_LIST_LOCATOR),

   432             results     = [],

   433             unfiltered  = response && response.results,

   434 

   435             filters,

   436             formatted,

   437             formatter,

   438             highlighted,

   439             highlighter,

   440             i,

   441             len,

   442             maxResults,

   443             result,

   444             text,

   445             textLocator;

   446 

   447         if (unfiltered && listLocator) {

   448             unfiltered = listLocator.call(this, unfiltered);

   449         }

   450 

   451         if (unfiltered && unfiltered.length) {

   452             filters     = this.get('resultFilters');

   453             textLocator = this.get('resultTextLocator');

   454 

   455             // Create a lightweight result object for each result to make them

   456             // easier to work with. The various properties on the object

   457             // represent different formats of the result, and will be populated

   458             // as we go.

   459             for (i = 0, len = unfiltered.length; i < len; ++i) {

   460                 result = unfiltered[i];

   461 

   462                 text = textLocator ?

   463                         textLocator.call(this, result) :

   464                         result.toString();

   465 

   466                 results.push({

   467                     display: Escape.html(text),

   468                     raw    : result,

   469                     text   : text

   470                 });

   471             }

   472 

   473             // Run the results through all configured result filters. Each

   474             // filter returns an array of (potentially fewer) result objects,

   475             // which is then passed to the next filter, and so on.

   476             for (i = 0, len = filters.length; i < len; ++i) {

   477                 results = filters[i].call(this, query, results.concat());

   478 

   479                 if (!results) {

   480                     Y.log("Filter didn't return anything.", 'warn', 'autocomplete-base');

   481                     return;

   482                 }

   483 

   484                 if (!results.length) {

   485                     break;

   486                 }

   487             }

   488 

   489             if (results.length) {

   490                 formatter   = this.get('resultFormatter');

   491                 highlighter = this.get('resultHighlighter');

   492                 maxResults  = this.get('maxResults');

   493 

   494                 // If maxResults is set and greater than 0, limit the number of

   495                 // results.

   496                 if (maxResults && maxResults > 0 &&

   497                         results.length > maxResults) {

   498                     results.length = maxResults;

   499                 }

   500 

   501                 // Run the results through the configured highlighter (if any).

   502                 // The highlighter returns an array of highlighted strings (not

   503                 // an array of result objects), and these strings are then added

   504                 // to each result object.

   505                 if (highlighter) {

   506                     highlighted = highlighter.call(this, query,

   507                             results.concat());

   508 

   509                     if (!highlighted) {

   510                         Y.log("Highlighter didn't return anything.", 'warn', 'autocomplete-base');

   511                         return;

   512                     }

   513 

   514                     for (i = 0, len = highlighted.length; i < len; ++i) {

   515                         result = results[i];

   516                         result.highlighted = highlighted[i];

   517                         result.display     = result.highlighted;

   518                     }

   519                 }

   520 

   521                 // Run the results through the configured formatter (if any) to

   522                 // produce the final formatted results. The formatter returns an

   523                 // array of strings or Node instances (not an array of result

   524                 // objects), and these strings/Nodes are then added to each

   525                 // result object.

   526                 if (formatter) {

   527                     formatted = formatter.call(this, query, results.concat());

   528 

   529                     if (!formatted) {

   530                         Y.log("Formatter didn't return anything.", 'warn', 'autocomplete-base');

   531                         return;

   532                     }

   533 

   534                     for (i = 0, len = formatted.length; i < len; ++i) {

   535                         results[i].display = formatted[i];

   536                     }

   537                 }

   538             }

   539         }

   540 

   541         facade.results = results;

   542         this.fire(EVT_RESULTS, facade);

   543     },

   544 

   545     /**

   546     Returns the query portion of the specified input value, or `null` if there

   547     is no suitable query within the input value.

   548 

   549     If a query delimiter is defined, the query will be the last delimited part

   550     of of the string.

   551 

   552     @method _parseValue

   553     @param {String} value Input value from which to extract the query.

   554     @return {String|null} query

   555     @protected

   556     **/

   557     _parseValue: function (value) {

   558         var delim = this.get(QUERY_DELIMITER);

   559 

   560         if (delim) {

   561             value = value.split(delim);

   562             value = value[value.length - 1];

   563         }

   564 

   565         return Lang.trimLeft(value);

   566     },

   567 

   568     /**

   569     Setter for the `enableCache` attribute.

   570 

   571     @method _setEnableCache

   572     @param {Boolean} value

   573     @protected

   574     @since 3.5.0

   575     **/

   576     _setEnableCache: function (value) {

   577         // When `this._cache` is an object, result sources will store cached

   578         // results in it. When it's falsy, they won't. This way result sources

   579         // don't need to get the value of the `enableCache` attribute on every

   580         // request, which would be sloooow.

   581         this._cache = value ? {} : null;

   582         Y.log('Cache ' + (value ? 'enabled' : 'disabled'), 'debug', 'autocomplete-base');

   583     },

   584 

   585     /**

   586     Setter for locator attributes.

   587 

   588     @method _setLocator

   589     @param {Function|String|null} locator

   590     @return {Function|null}

   591     @protected

   592     **/

   593     _setLocator: function (locator) {

   594         if (this[_FUNCTION_VALIDATOR](locator)) {

   595             return locator;

   596         }

   597 

   598         var that = this;

   599 

   600         locator = locator.toString().split('.');

   601 

   602         return function (result) {

   603             return result && that._getObjectValue(result, locator);

   604         };

   605     },

   606 

   607     /**

   608     Setter for the `requestTemplate` attribute.

   609 

   610     @method _setRequestTemplate

   611     @param {Function|String|null} template

   612     @return {Function|null}

   613     @protected

   614     **/

   615     _setRequestTemplate: function (template) {

   616         if (this[_FUNCTION_VALIDATOR](template)) {

   617             return template;

   618         }

   619 

   620         template = template.toString();

   621 

   622         return function (query) {

   623             return Lang.sub(template, {query: encodeURIComponent(query)});

   624         };

   625     },

   626 

   627     /**

   628     Setter for the `resultFilters` attribute.

   629 

   630     @method _setResultFilters

   631     @param {Array|Function|String|null} filters `null`, a filter

   632         function, an array of filter functions, or a string or array of strings

   633         representing the names of methods on `Y.AutoCompleteFilters`.

   634     @return {Function[]} Array of filter functions (empty if <i>filters</i> is

   635         `null`).

   636     @protected

   637     **/

   638     _setResultFilters: function (filters) {

   639         var acFilters, getFilterFunction;

   640 

   641         if (filters === null) {

   642             return [];

   643         }

   644 

   645         acFilters = Y.AutoCompleteFilters;

   646 

   647         getFilterFunction = function (filter) {

   648             if (isFunction(filter)) {

   649                 return filter;

   650             }

   651 

   652             if (isString(filter) && acFilters &&

   653                     isFunction(acFilters[filter])) {

   654                 return acFilters[filter];

   655             }

   656 

   657             return false;

   658         };

   659 

   660         if (Lang.isArray(filters)) {

   661             filters = YArray.map(filters, getFilterFunction);

   662             return YArray.every(filters, function (f) { return !!f; }) ?

   663                     filters : INVALID_VALUE;

   664         } else {

   665             filters = getFilterFunction(filters);

   666             return filters ? [filters] : INVALID_VALUE;

   667         }

   668     },

   669 

   670     /**

   671     Setter for the `resultHighlighter` attribute.

   672 

   673     @method _setResultHighlighter

   674     @param {Function|String|null} highlighter `null`, a highlighter function, or

   675         a string representing the name of a method on

   676         `Y.AutoCompleteHighlighters`.

   677     @return {Function|null}

   678     @protected

   679     **/

   680     _setResultHighlighter: function (highlighter) {

   681         var acHighlighters;

   682 

   683         if (this[_FUNCTION_VALIDATOR](highlighter)) {

   684             return highlighter;

   685         }

   686 

   687         acHighlighters = Y.AutoCompleteHighlighters;

   688 

   689         if (isString(highlighter) && acHighlighters &&

   690                 isFunction(acHighlighters[highlighter])) {

   691             return acHighlighters[highlighter];

   692         }

   693 

   694         return INVALID_VALUE;

   695     },

   696 

   697     /**

   698     Setter for the `source` attribute. Returns a DataSource or a DataSource-like

   699     object depending on the type of _source_ and/or the value of the

   700     `sourceType` attribute.

   701 

   702     @method _setSource

   703     @param {Any} source AutoComplete source. See the `source` attribute for

   704         details.

   705     @return {DataSource|Object}

   706     @protected

   707     **/

   708     _setSource: function (source) {

   709         var sourceType = this.get('sourceType') || Lang.type(source),

   710             sourceSetter;

   711 

   712         if ((source && isFunction(source.sendRequest))

   713                 || source === null

   714                 || sourceType === 'datasource') {

   715 

   716             // Quacks like a DataSource instance (or null). Make it so!

   717             this._rawSource = source;

   718             return source;

   719         }

   720 

   721         // See if there's a registered setter for this source type.

   722         if ((sourceSetter = AutoCompleteBase.SOURCE_TYPES[sourceType])) {

   723             this._rawSource = source;

   724             return Lang.isString(sourceSetter) ?

   725                     this[sourceSetter](source) : sourceSetter(source);

   726         }

   727 

   728         Y.error("Unsupported source type '" + sourceType + "'. Maybe autocomplete-sources isn't loaded?");

   729         return INVALID_VALUE;

   730     },

   731 

   732     /**

   733     Shared success callback for non-DataSource sources.

   734 

   735     @method _sourceSuccess

   736     @param {Any} data Response data.

   737     @param {Object} request Request object.

   738     @protected

   739     **/

   740     _sourceSuccess: function (data, request) {

   741         request.callback.success({

   742             data: data,

   743             response: {results: data}

   744         });

   745     },

   746 

   747     /**

   748     Synchronizes the UI state of the `allowBrowserAutocomplete` attribute.

   749 

   750     @method _syncBrowserAutocomplete

   751     @protected

   752     **/

   753     _syncBrowserAutocomplete: function () {

   754         var inputNode = this.get(INPUT_NODE);

   755 

   756         if (inputNode.get('nodeName').toLowerCase() === 'input') {

   757             inputNode.setAttribute('autocomplete',

   758                     this.get(ALLOW_BROWSER_AC) ? 'on' : 'off');

   759         }

   760     },

   761 

   762     /**

   763     Updates the query portion of the `value` attribute.

   764 

   765     If a query delimiter is defined, the last delimited portion of the input

   766     value will be replaced with the specified _value_.

   767 

   768     @method _updateValue

   769     @param {String} newVal New value.

   770     @protected

   771     **/

   772     _updateValue: function (newVal) {

   773         var delim = this.get(QUERY_DELIMITER),

   774             insertDelim,

   775             len,

   776             prevVal;

   777 

   778         newVal = Lang.trimLeft(newVal);

   779 

   780         if (delim) {

   781             insertDelim = trim(delim); // so we don't double up on spaces

   782             prevVal     = YArray.map(trim(this.get(VALUE)).split(delim), trim);

   783             len         = prevVal.length;

   784 

   785             if (len > 1) {

   786                 prevVal[len - 1] = newVal;

   787                 newVal = prevVal.join(insertDelim + ' ');

   788             }

   789 

   790             newVal = newVal + insertDelim + ' ';

   791         }

   792 

   793         this.set(VALUE, newVal);

   794     },

   795 

   796     // -- Protected Event Handlers ---------------------------------------------

   797 

   798     /**

   799     Updates the current `source` based on the new `sourceType` to ensure that

   800     the two attributes don't get out of sync when they're changed separately.

   801 

   802     @method _afterSourceTypeChange

   803     @param {EventFacade} e

   804     @protected

   805     **/

   806     _afterSourceTypeChange: function (e) {

   807         if (this._rawSource) {

   808             this.set('source', this._rawSource);

   809         }

   810     },

   811 

   812     /**

   813     Handles change events for the `value` attribute.

   814 

   815     @method _afterValueChange

   816     @param {EventFacade} e

   817     @protected

   818     **/

   819     _afterValueChange: function (e) {

   820         var newVal   = e.newVal,

   821             self     = this,

   822             uiChange = e.src === AutoCompleteBase.UI_SRC,

   823             delay, fire, minQueryLength, query;

   824 

   825         // Update the UI if the value was changed programmatically.

   826         if (!uiChange) {

   827             self._inputNode.set(VALUE, newVal);

   828         }

   829 

   830         Y.log('valueChange: new: "' + newVal + '"; old: "' + e.prevVal + '"', 'info', 'autocomplete-base');

   831 

   832         minQueryLength = self.get('minQueryLength');

   833         query          = self._parseValue(newVal) || '';

   834 

   835         if (minQueryLength >= 0 && query.length >= minQueryLength) {

   836             // Only query on changes that originate from the UI.

   837             if (uiChange) {

   838                 delay = self.get('queryDelay');

   839 

   840                 fire = function () {

   841                     self.fire(EVT_QUERY, {

   842                         inputValue: newVal,

   843                         query     : query,

   844                         src       : e.src

   845                     });

   846                 };

   847 

   848                 if (delay) {

   849                     clearTimeout(self._delay);

   850                     self._delay = setTimeout(fire, delay);

   851                 } else {

   852                     fire();

   853                 }

   854             } else {

   855                 // For programmatic value changes, just update the query

   856                 // attribute without sending a query.

   857                 self._set(QUERY, query);

   858             }

   859         } else {

   860             clearTimeout(self._delay);

   861 

   862             self.fire(EVT_CLEAR, {

   863                 prevVal: e.prevVal ? self._parseValue(e.prevVal) : null,

   864                 src    : e.src

   865             });

   866         }

   867     },

   868 

   869     /**

   870     Handles `blur` events on the input node.

   871 

   872     @method _onInputBlur

   873     @param {EventFacade} e

   874     @protected

   875     **/

   876     _onInputBlur: function (e) {

   877         var delim = this.get(QUERY_DELIMITER),

   878             delimPos,

   879             newVal,

   880             value;

   881 

   882         // If a query delimiter is set and the input's value contains one or

   883         // more trailing delimiters, strip them.

   884         if (delim && !this.get('allowTrailingDelimiter')) {

   885             delim = Lang.trimRight(delim);

   886             value = newVal = this._inputNode.get(VALUE);

   887 

   888             if (delim) {

   889                 while ((newVal = Lang.trimRight(newVal)) &&

   890                         (delimPos = newVal.length - delim.length) &&

   891                         newVal.lastIndexOf(delim) === delimPos) {

   892 

   893                     newVal = newVal.substring(0, delimPos);

   894                 }

   895             } else {

   896                 // Delimiter is one or more space characters, so just trim the

   897                 // value.

   898                 newVal = Lang.trimRight(newVal);

   899             }

   900 

   901             if (newVal !== value) {

   902                 this.set(VALUE, newVal);

   903             }

   904         }

   905     },

   906 

   907     /**

   908     Handles `valueChange` events on the input node and fires a `query` event

   909     when the input value meets the configured criteria.

   910 

   911     @method _onInputValueChange

   912     @param {EventFacade} e

   913     @protected

   914     **/

   915     _onInputValueChange: function (e) {

   916         var newVal = e.newVal;

   917 

   918         // Don't query if the internal value is the same as the new value

   919         // reported by valueChange.

   920         if (newVal !== this.get(VALUE)) {

   921             this.set(VALUE, newVal, {src: AutoCompleteBase.UI_SRC});

   922         }

   923     },

   924 

   925     /**

   926     Handles source responses and fires the `results` event.

   927 

   928     @method _onResponse

   929     @param {EventFacade} e

   930     @protected

   931     **/

   932     _onResponse: function (query, e) {

   933         // Ignore stale responses that aren't for the current query.

   934         if (query === (this.get(QUERY) || '')) {

   935             this._parseResponse(query || '', e.response, e.data);

   936         }

   937     },

   938 

   939     // -- Protected Default Event Handlers -------------------------------------

   940 

   941     /**

   942     Default `clear` event handler. Sets the `results` attribute to an empty

   943     array and `query` to null.

   944 

   945     @method _defClearFn

   946     @protected

   947     **/

   948     _defClearFn: function () {

   949         this._set(QUERY, null);

   950         this._set(RESULTS, []);

   951     },

   952 

   953     /**

   954     Default `query` event handler. Sets the `query` attribute and sends a

   955     request to the source if one is configured.

   956 

   957     @method _defQueryFn

   958     @param {EventFacade} e

   959     @protected

   960     **/

   961     _defQueryFn: function (e) {

   962         Y.log('query: "' + e.query + '"; inputValue: "' + e.inputValue + '"', 'info', 'autocomplete-base');

   963         this.sendRequest(e.query); // sendRequest will set the 'query' attribute

   964     },

   965 

   966     /**

   967     Default `results` event handler. Sets the `results` attribute to the latest

   968     results.

   969 

   970     @method _defResultsFn

   971     @param {EventFacade} e

   972     @protected

   973     **/

   974     _defResultsFn: function (e) {

   975         Y.log('results: ' + Y.dump(e.results), 'info', 'autocomplete-base');

   976         this._set(RESULTS, e[RESULTS]);

   977     }

   978 };

   979 

   980 AutoCompleteBase.ATTRS = {

   981     /**

   982     Whether or not to enable the browser's built-in autocomplete functionality

   983     for input fields.

   984 

   985     @attribute allowBrowserAutocomplete

   986     @type Boolean

   987     @default false

   988     **/

   989     allowBrowserAutocomplete: {

   990         value: false

   991     },

   992 

   993     /**

   994     When a `queryDelimiter` is set, trailing delimiters will automatically be

   995     stripped from the input value by default when the input node loses focus.

   996     Set this to `true` to allow trailing delimiters.

   997 

   998     @attribute allowTrailingDelimiter

   999     @type Boolean

  1000     @default false

  1001     **/

  1002     allowTrailingDelimiter: {

  1003         value: false

  1004     },

  1005 

  1006     /**

  1007     Whether or not to enable in-memory caching in result sources that support

  1008     it.

  1009 

  1010     @attribute enableCache

  1011     @type Boolean

  1012     @default true

  1013     @since 3.5.0

  1014     **/

  1015     enableCache: {

  1016         lazyAdd: false, // we need the setter to run on init

  1017         setter: '_setEnableCache',

  1018         value: true

  1019     },

  1020 

  1021     /**

  1022     Node to monitor for changes, which will generate `query` events when

  1023     appropriate. May be either an `<input>` or a `<textarea>`.

  1024 

  1025     @attribute inputNode

  1026     @type Node|HTMLElement|String

  1027     @initOnly

  1028     **/

  1029     inputNode: {

  1030         setter: Y.one,

  1031         writeOnce: 'initOnly'

  1032     },

  1033 

  1034     /**

  1035     Maximum number of results to return. A value of `0` or less will allow an

  1036     unlimited number of results.

  1037 

  1038     @attribute maxResults

  1039     @type Number

  1040     @default 0

  1041     **/

  1042     maxResults: {

  1043         value: 0

  1044     },

  1045 

  1046     /**

  1047     Minimum number of characters that must be entered before a `query` event

  1048     will be fired. A value of `0` allows empty queries; a negative value will

  1049     effectively disable all `query` events.

  1050 

  1051     @attribute minQueryLength

  1052     @type Number

  1053     @default 1

  1054     **/

  1055     minQueryLength: {

  1056         value: 1

  1057     },

  1058 

  1059     /**

  1060     Current query, or `null` if there is no current query.

  1061 

  1062     The query might not be the same as the current value of the input node, both

  1063     for timing reasons (due to `queryDelay`) and because when one or more

  1064     `queryDelimiter` separators are in use, only the last portion of the

  1065     delimited input string will be used as the query value.

  1066 

  1067     @attribute query

  1068     @type String|null

  1069     @default null

  1070     @readonly

  1071     **/

  1072     query: {

  1073         readOnly: true,

  1074         value: null

  1075     },

  1076 

  1077     /**

  1078     Number of milliseconds to delay after input before triggering a `query`

  1079     event. If new input occurs before this delay is over, the previous input

  1080     event will be ignored and a new delay will begin.

  1081 

  1082     This can be useful both to throttle queries to a remote data source and to

  1083     avoid distracting the user by showing them less relevant results before

  1084     they've paused their typing.

  1085 

  1086     @attribute queryDelay

  1087     @type Number

  1088     @default 100

  1089     **/

  1090     queryDelay: {

  1091         value: 100

  1092     },

  1093 

  1094     /**

  1095     Query delimiter string. When a delimiter is configured, the input value

  1096     will be split on the delimiter, and only the last portion will be used in

  1097     autocomplete queries and updated when the `query` attribute is

  1098     modified.

  1099 

  1100     @attribute queryDelimiter

  1101     @type String|null

  1102     @default null

  1103     **/

  1104     queryDelimiter: {

  1105         value: null

  1106     },

  1107 

  1108     /**

  1109     Source request template. This can be a function that accepts a query as a

  1110     parameter and returns a request string, or it can be a string containing the

  1111     placeholder "{query}", which will be replaced with the actual URI-encoded

  1112     query. In either case, the resulting string will be appended to the request

  1113     URL when the `source` attribute is set to a remote DataSource, JSONP URL, or

  1114     XHR URL (it will not be appended to YQL URLs).

  1115 

  1116     While `requestTemplate` may be set to either a function or a string, it will

  1117     always be returned as a function that accepts a query argument and returns a

  1118     string.

  1119 

  1120     @attribute requestTemplate

  1121     @type Function|String|null

  1122     @default null

  1123     **/

  1124     requestTemplate: {

  1125         setter: '_setRequestTemplate',

  1126         value: null

  1127     },

  1128 

  1129     /**

  1130     Array of local result filter functions. If provided, each filter will be

  1131     called with two arguments when results are received: the query and an array

  1132     of result objects. See the documentation for the `results` event for a list

  1133     of the properties available on each result object.

  1134 

  1135     Each filter is expected to return a filtered or modified version of the

  1136     results array, which will then be passed on to subsequent filters, then the