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 

   235             source.sendRequest({

   236                 query  : query,

   237                 request: request,

   238 

   239                 callback: {

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

   241                 }

   242             });

   243         }

   244 

   245         return this;

   246     },

   247 

   248     // -- Protected Lifecycle Methods ------------------------------------------

   249 

   250     /**

   251     Attaches event listeners and behaviors.

   252 

   253     @method _bindUIACBase

   254     @protected

   255     **/

   256     _bindUIACBase: function () {

   257         var inputNode  = this.get(INPUT_NODE),

   258             tokenInput = inputNode && inputNode.tokenInput;

   259 

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

   261         // plugin's inputNode instead.

   262         if (tokenInput) {

   263             inputNode = tokenInput.get(INPUT_NODE);

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

   265         }

   266 

   267         if (!inputNode) {

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

   269             return;

   270         }

   271 

   272         this._inputNode = inputNode;

   273 

   274         this._acBaseEvents = new Y.EventHandle([

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

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

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

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

   279 

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

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

   282             this.after(VALUE_CHANGE, this._afterValueChange)

   283         ]);

   284     },

   285 

   286     /**

   287     Synchronizes the UI state of the `inputNode`.

   288 

   289     @method _syncUIACBase

   290     @protected

   291     **/

   292     _syncUIACBase: function () {

   293         this._syncBrowserAutocomplete();

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

   295     },

   296 

   297     // -- Protected Prototype Methods ------------------------------------------

   298 

   299     /**

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

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

   302 

   303     @method _createArraySource

   304     @param {Array} source

   305     @return {Object} DataSource-like object.

   306     @protected

   307     **/

   308     _createArraySource: function (source) {

   309         var that = this;

   310 

   311         return {

   312             type: 'array',

   313             sendRequest: function (request) {

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

   315             }

   316         };

   317     },

   318 

   319     /**

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

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

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

   323 

   324     @method _createFunctionSource

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

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

   327     @return {Object} DataSource-like object.

   328     @protected

   329     **/

   330     _createFunctionSource: function (source) {

   331         var that = this;

   332 

   333         return {

   334             type: 'function',

   335             sendRequest: function (request) {

   336                 var value;

   337 

   338                 function afterResults(results) {

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

   340                 }

   341 

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

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

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

   345                     afterResults(value);

   346                 }

   347             }

   348         };

   349     },

   350 

   351     /**

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

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

   354     the `source` attribute for more details.

   355 

   356     @method _createObjectSource

   357     @param {Object} source

   358     @return {Object} DataSource-like object.

   359     @protected

   360     **/

   361     _createObjectSource: function (source) {

   362         var that = this;

   363 

   364         return {

   365             type: 'object',

   366             sendRequest: function (request) {

   367                 var query = request.query;

   368 

   369                 that[_SOURCE_SUCCESS](

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

   371                     request

   372                 );

   373             }

   374         };

   375     },

   376 

   377     /**

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

   379 

   380     @method _functionValidator

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

   382     @protected

   383     **/

   384     _functionValidator: function (value) {

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

   386     },

   387 

   388     /**

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

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

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

   392     neither `undefined` nor an object.

   393 

   394     @method _getObjectValue

   395     @param {Object} obj

   396     @param {Array} path

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

   398         not found at the specified path.

   399     @protected

   400     **/

   401     _getObjectValue: function (obj, path) {

   402         if (!obj) {

   403             return;

   404         }

   405 

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

   407             obj = obj[path[i]];

   408         }

   409 

   410         return obj;

   411     },

   412 

   413     /**

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

   415     `results` event.

   416 

   417     @method _parseResponse

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

   419     @param {Object} response Response containing results.

   420     @param {Object} data Raw response data.

   421     @protected

   422     **/

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

   424         var facade = {

   425                 data   : data,

   426                 query  : query,

   427                 results: []

   428             },

   429 

   430             listLocator = this.get(RESULT_LIST_LOCATOR),

   431             results     = [],

   432             unfiltered  = response && response.results,

   433 

   434             filters,

   435             formatted,

   436             formatter,

   437             highlighted,

   438             highlighter,

   439             i,

   440             len,

   441             maxResults,

   442             result,

   443             text,

   444             textLocator;

   445 

   446         if (unfiltered && listLocator) {

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

   448         }

   449 

   450         if (unfiltered && unfiltered.length) {

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

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

   453 

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

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

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

   457             // as we go.

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

   459                 result = unfiltered[i];

   460 

   461                 text = textLocator ?

   462                         textLocator.call(this, result) :

   463                         result.toString();

   464 

   465                 results.push({

   466                     display: Escape.html(text),

   467                     raw    : result,

   468                     text   : text

   469                 });

   470             }

   471 

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

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

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

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

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

   477 

   478                 if (!results) {

   479                     return;

   480                 }

   481 

   482                 if (!results.length) {

   483                     break;

   484                 }

   485             }

   486 

   487             if (results.length) {

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

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

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

   491 

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

   493                 // results.

   494                 if (maxResults && maxResults > 0 &&

   495                         results.length > maxResults) {

   496                     results.length = maxResults;

   497                 }

   498 

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

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

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

   502                 // to each result object.

   503                 if (highlighter) {

   504                     highlighted = highlighter.call(this, query,

   505                             results.concat());

   506 

   507                     if (!highlighted) {

   508                         return;

   509                     }

   510 

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

   512                         result = results[i];

   513                         result.highlighted = highlighted[i];

   514                         result.display     = result.highlighted;

   515                     }

   516                 }

   517 

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

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

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

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

   522                 // result object.

   523                 if (formatter) {

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

   525 

   526                     if (!formatted) {

   527                         return;

   528                     }

   529 

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

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

   532                     }

   533                 }

   534             }

   535         }

   536 

   537         facade.results = results;

   538         this.fire(EVT_RESULTS, facade);

   539     },

   540 

   541     /**

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

   543     is no suitable query within the input value.

   544 

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

   546     of of the string.

   547 

   548     @method _parseValue

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

   550     @return {String|null} query

   551     @protected

   552     **/

   553     _parseValue: function (value) {

   554         var delim = this.get(QUERY_DELIMITER);

   555 

   556         if (delim) {

   557             value = value.split(delim);

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

   559         }

   560 

   561         return Lang.trimLeft(value);

   562     },

   563 

   564     /**

   565     Setter for the `enableCache` attribute.

   566 

   567     @method _setEnableCache

   568     @param {Boolean} value

   569     @protected

   570     @since 3.5.0

   571     **/

   572     _setEnableCache: function (value) {

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

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

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

   576         // request, which would be sloooow.

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

   578     },

   579 

   580     /**

   581     Setter for locator attributes.

   582 

   583     @method _setLocator

   584     @param {Function|String|null} locator

   585     @return {Function|null}

   586     @protected

   587     **/

   588     _setLocator: function (locator) {

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

   590             return locator;

   591         }

   592 

   593         var that = this;

   594 

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

   596 

   597         return function (result) {

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

   599         };

   600     },

   601 

   602     /**

   603     Setter for the `requestTemplate` attribute.

   604 

   605     @method _setRequestTemplate

   606     @param {Function|String|null} template

   607     @return {Function|null}

   608     @protected

   609     **/

   610     _setRequestTemplate: function (template) {

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

   612             return template;

   613         }

   614 

   615         template = template.toString();

   616 

   617         return function (query) {

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

   619         };

   620     },

   621 

   622     /**

   623     Setter for the `resultFilters` attribute.

   624 

   625     @method _setResultFilters

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

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

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

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

   630         `null`).

   631     @protected

   632     **/

   633     _setResultFilters: function (filters) {

   634         var acFilters, getFilterFunction;

   635 

   636         if (filters === null) {

   637             return [];

   638         }

   639 

   640         acFilters = Y.AutoCompleteFilters;

   641 

   642         getFilterFunction = function (filter) {

   643             if (isFunction(filter)) {

   644                 return filter;

   645             }

   646 

   647             if (isString(filter) && acFilters &&

   648                     isFunction(acFilters[filter])) {

   649                 return acFilters[filter];

   650             }

   651 

   652             return false;

   653         };

   654 

   655         if (Lang.isArray(filters)) {

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

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

   658                     filters : INVALID_VALUE;

   659         } else {

   660             filters = getFilterFunction(filters);

   661             return filters ? [filters] : INVALID_VALUE;

   662         }

   663     },

   664 

   665     /**

   666     Setter for the `resultHighlighter` attribute.

   667 

   668     @method _setResultHighlighter

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

   670         a string representing the name of a method on

   671         `Y.AutoCompleteHighlighters`.

   672     @return {Function|null}

   673     @protected

   674     **/

   675     _setResultHighlighter: function (highlighter) {

   676         var acHighlighters;

   677 

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

   679             return highlighter;

   680         }

   681 

   682         acHighlighters = Y.AutoCompleteHighlighters;

   683 

   684         if (isString(highlighter) && acHighlighters &&

   685                 isFunction(acHighlighters[highlighter])) {

   686             return acHighlighters[highlighter];

   687         }

   688 

   689         return INVALID_VALUE;

   690     },

   691 

   692     /**

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

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

   695     `sourceType` attribute.

   696 

   697     @method _setSource

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

   699         details.

   700     @return {DataSource|Object}

   701     @protected

   702     **/

   703     _setSource: function (source) {

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

   705             sourceSetter;

   706 

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

   708                 || source === null

   709                 || sourceType === 'datasource') {

   710 

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

   712             this._rawSource = source;

   713             return source;

   714         }

   715 

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

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

   718             this._rawSource = source;

   719             return Lang.isString(sourceSetter) ?

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

   721         }

   722 

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

   724         return INVALID_VALUE;

   725     },

   726 

   727     /**

   728     Shared success callback for non-DataSource sources.

   729 

   730     @method _sourceSuccess

   731     @param {Any} data Response data.

   732     @param {Object} request Request object.

   733     @protected

   734     **/

   735     _sourceSuccess: function (data, request) {

   736         request.callback.success({

   737             data: data,

   738             response: {results: data}

   739         });

   740     },

   741 

   742     /**

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

   744 

   745     @method _syncBrowserAutocomplete

   746     @protected

   747     **/

   748     _syncBrowserAutocomplete: function () {

   749         var inputNode = this.get(INPUT_NODE);

   750 

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

   752             inputNode.setAttribute('autocomplete',

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

   754         }

   755     },

   756 

   757     /**

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

   759 

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

   761     value will be replaced with the specified _value_.

   762 

   763     @method _updateValue

   764     @param {String} newVal New value.

   765     @protected

   766     **/

   767     _updateValue: function (newVal) {

   768         var delim = this.get(QUERY_DELIMITER),

   769             insertDelim,

   770             len,

   771             prevVal;

   772 

   773         newVal = Lang.trimLeft(newVal);

   774 

   775         if (delim) {

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

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

   778             len         = prevVal.length;

   779 

   780             if (len > 1) {

   781                 prevVal[len - 1] = newVal;

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

   783             }

   784 

   785             newVal = newVal + insertDelim + ' ';

   786         }

   787 

   788         this.set(VALUE, newVal);

   789     },

   790 

   791     // -- Protected Event Handlers ---------------------------------------------

   792 

   793     /**

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

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

   796 

   797     @method _afterSourceTypeChange

   798     @param {EventFacade} e

   799     @protected

   800     **/

   801     _afterSourceTypeChange: function (e) {

   802         if (this._rawSource) {

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

   804         }

   805     },

   806 

   807     /**

   808     Handles change events for the `value` attribute.

   809 

   810     @method _afterValueChange

   811     @param {EventFacade} e

   812     @protected

   813     **/

   814     _afterValueChange: function (e) {

   815         var newVal   = e.newVal,

   816             self     = this,

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

   818             delay, fire, minQueryLength, query;

   819 

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

   821         if (!uiChange) {

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

   823         }

   824 

   825 

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

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

   828 

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

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

   831             if (uiChange) {

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

   833 

   834                 fire = function () {

   835                     self.fire(EVT_QUERY, {

   836                         inputValue: newVal,

   837                         query     : query,

   838                         src       : e.src

   839                     });

   840                 };

   841 

   842                 if (delay) {

   843                     clearTimeout(self._delay);

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

   845                 } else {

   846                     fire();

   847                 }

   848             } else {

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

   850                 // attribute without sending a query.

   851                 self._set(QUERY, query);

   852             }

   853         } else {

   854             clearTimeout(self._delay);

   855 

   856             self.fire(EVT_CLEAR, {

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

   858                 src    : e.src

   859             });

   860         }

   861     },

   862 

   863     /**

   864     Handles `blur` events on the input node.

   865 

   866     @method _onInputBlur

   867     @param {EventFacade} e

   868     @protected

   869     **/

   870     _onInputBlur: function (e) {

   871         var delim = this.get(QUERY_DELIMITER),

   872             delimPos,

   873             newVal,

   874             value;

   875 

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

   877         // more trailing delimiters, strip them.

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

   879             delim = Lang.trimRight(delim);

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

   881 

   882             if (delim) {

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

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

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

   886 

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

   888                 }

   889             } else {

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

   891                 // value.

   892                 newVal = Lang.trimRight(newVal);

   893             }

   894 

   895             if (newVal !== value) {

   896                 this.set(VALUE, newVal);

   897             }

   898         }

   899     },

   900 

   901     /**

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

   903     when the input value meets the configured criteria.

   904 

   905     @method _onInputValueChange

   906     @param {EventFacade} e

   907     @protected

   908     **/

   909     _onInputValueChange: function (e) {

   910         var newVal = e.newVal;

   911 

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

   913         // reported by valueChange.

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

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

   916         }

   917     },

   918 

   919     /**

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

   921 

   922     @method _onResponse

   923     @param {EventFacade} e

   924     @protected

   925     **/

   926     _onResponse: function (query, e) {

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

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

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

   930         }

   931     },

   932 

   933     // -- Protected Default Event Handlers -------------------------------------

   934 

   935     /**

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

   937     array and `query` to null.

   938 

   939     @method _defClearFn

   940     @protected

   941     **/

   942     _defClearFn: function () {

   943         this._set(QUERY, null);

   944         this._set(RESULTS, []);

   945     },

   946 

   947     /**

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

   949     request to the source if one is configured.

   950 

   951     @method _defQueryFn

   952     @param {EventFacade} e

   953     @protected

   954     **/

   955     _defQueryFn: function (e) {

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

   957     },

   958 

   959     /**

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

   961     results.

   962 

   963     @method _defResultsFn

   964     @param {EventFacade} e

   965     @protected

   966     **/

   967     _defResultsFn: function (e) {

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

   969     }

   970 };

   971 

   972 AutoCompleteBase.ATTRS = {

   973     /**

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

   975     for input fields.

   976 

   977     @attribute allowBrowserAutocomplete

   978     @type Boolean

   979     @default false

   980     **/

   981     allowBrowserAutocomplete: {

   982         value: false

   983     },

   984 

   985     /**

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

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

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

   989 

   990     @attribute allowTrailingDelimiter

   991     @type Boolean

   992     @default false

   993     **/

   994     allowTrailingDelimiter: {

   995         value: false

   996     },

   997 

   998     /**

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

  1000     it.

  1001 

  1002     @attribute enableCache

  1003     @type Boolean

  1004     @default true

  1005     @since 3.5.0

  1006     **/

  1007     enableCache: {

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

  1009         setter: '_setEnableCache',

  1010         value: true

  1011     },

  1012 

  1013     /**

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

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

  1016 

  1017     @attribute inputNode

  1018     @type Node|HTMLElement|String

  1019     @initOnly

  1020     **/

  1021     inputNode: {

  1022         setter: Y.one,

  1023         writeOnce: 'initOnly'

  1024     },

  1025 

  1026     /**

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

  1028     unlimited number of results.

  1029 

  1030     @attribute maxResults

  1031     @type Number

  1032     @default 0

  1033     **/

  1034     maxResults: {

  1035         value: 0

  1036     },

  1037 

  1038     /**

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

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

  1041     effectively disable all `query` events.

  1042 

  1043     @attribute minQueryLength

  1044     @type Number

  1045     @default 1

  1046     **/

  1047     minQueryLength: {

  1048         value: 1

  1049     },

  1050 

  1051     /**

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

  1053 

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

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

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

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

  1058 

  1059     @attribute query

  1060     @type String|null

  1061     @default null

  1062     @readonly

  1063     **/

  1064     query: {

  1065         readOnly: true,

  1066         value: null

  1067     },

  1068 

  1069     /**

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

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

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

  1073 

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

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

  1076     they've paused their typing.

  1077 

  1078     @attribute queryDelay

  1079     @type Number

  1080     @default 100

  1081     **/

  1082     queryDelay: {

  1083         value: 100

  1084     },

  1085 

  1086     /**

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

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

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

  1090     modified.

  1091 

  1092     @attribute queryDelimiter

  1093     @type String|null

  1094     @default null

  1095     **/

  1096     queryDelimiter: {

  1097         value: null

  1098     },

  1099 

  1100     /**

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

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

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

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

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

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

  1107 

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

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

  1110     string.

  1111 

  1112     @attribute requestTemplate

  1113     @type Function|String|null

  1114     @default null

  1115     **/

  1116     requestTemplate: {

  1117         setter: '_setRequestTemplate',

  1118         value: null

  1119     },

  1120 

  1121     /**

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

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

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

  1125     of the properties available on each result object.

  1126 

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

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

  1129     `resultHighlighter` function (if set), then the `resultFormatter` function

  1130     (if set), and finally to subscribers to the `results` event.

  1131 

  1132     If no `source` is set, result filters will not be called.

  1133 

  1134     Prepackaged result filters provided by the autocomplete-filters and

  1135     autocomplete-filters-accentfold modules can be used by specifying the filter

  1136     name as a string, such as `'phraseMatch'` (assuming the necessary filters