AutoCompleteBase Class
+ + + + +Extension that provides core autocomplete logic (but no UI implementation) for a +text input field or textarea.
+ +The AutoCompleteBase class provides events and attributes that abstract away
+core autocomplete logic and configuration, but does not provide a widget
+implementation or suggestion UI. For a prepackaged autocomplete widget, see
+AutoCompleteList.
This extension cannot be instantiated directly, since it doesn't provide an
+actual implementation. It's intended to be mixed into a Y.Base-based class or
+widget.
Y.Widget-based example:
YUI().use('autocomplete-base', 'widget', function (Y) {
+ var MyAC = Y.Base.create('myAC', Y.Widget, [Y.AutoCompleteBase], {
+ // Custom prototype methods and properties.
+ }, {
+ // Custom static methods and properties.
+ });
+
+ // Custom implementation code.
+});
+Y.Base-based example:
YUI().use('autocomplete-base', function (Y) {
+ var MyAC = Y.Base.create('myAC', Y.Base, [Y.AutoCompleteBase], {
+ initializer: function () {
+ this._bindUIACBase();
+ this._syncUIACBase();
+ },
+
+ // Custom prototype methods and properties.
+ }, {
+ // Custom static methods and properties.
+ });
+
+ // Custom implementation code.
+});
+-
+
- Index + + +
- Methods + + +
- Properties + + +
- Attributes + + +
- Events + +
Item Index
+ + +Methods
+ +-
+
+
- + _afterSourceTypeChange + + + + + +
- + _afterValueChange + + + + + +
- + _beforeCreateObjectSource + + + + + +
- + _bindUIACBase + + + + + +
- + _createArraySource + + + + + +
- + _createFunctionSource + + + + + +
- + _createIOSource + + + + + +
- + _createJSONPSource + + + + + +
- + _createObjectSource + + + + + +
- + _createSelectSource + + + + + +
- + _createStringSource + + + + + +
- + _createYQLSource + + + + + +
- + _defaultYQLLocator + + + + + +
- + _defClearFn + + + + + +
- + _defQueryFn + + + + + +
- + _defResultsFn + + + + + +
- + _functionValidator + + + + + +
- + _getObjectValue + + + + + +
- + _getXHRUrl + + + + + +
- + _jsonpFormatter + + + + + +
- + _onInputBlur + + + + + +
- + _onInputValueChange + + + + + +
- + _onResponse + + + + + +
- + _parseResponse + + + + + +
- + _parseValue + + + + + +
- + _setEnableCache + + + + + +
- + _setLocator + + + + + +
- + _setRequestTemplate + + + + + +
- + _setResultFilters + + + + + +
- + _setResultHighlighter + + + + + +
- + _setSource + + + + + +
- + _sourceSuccess + + + + + +
- + _syncBrowserAutocomplete + + + + + +
- + _syncUIACBase + + + + + +
- + _updateValue + + + + + +
- + clearCache + + + + + +
- + sendRequest + + + + + +
Properties
+ +-
+
+
- + _YQL_SOURCE_REGEX + + + + + +
- + SOURCE_TYPES + + + static + + + + +
Attributes
+ +-
+
+
- + allowBrowserAutocomplete + + +
- + allowTrailingDelimiter + + +
- + enableCache + + +
- + inputNode + + +
- + maxResults + + +
- + minQueryLength + + +
- + query + + +
- + queryDelay + + +
- + queryDelimiter + + +
- + requestTemplate + + +
- + resultFilters + + +
- + resultFormatter + + +
- + resultHighlighter + + +
- + resultListLocator + + +
- + results + + +
- + resultTextLocator + + +
- + source + + +
- + sourceType + + +
- + tokenInput + + +
- + value + + +
- + yqlEnv + + +
- + yqlProtocol + + +
Methods
+ + +_afterSourceTypeChange
+
+
+ -
+
+
-
+
+
e+ +
+
+
Updates the current source based on the new sourceType to ensure that
+the two attributes don't get out of sync when they're changed separately.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_afterValueChange
+
+
+ -
+
+
-
+
+
e+ +
+
+
Handles change events for the value attribute.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_beforeCreateObjectSource
+
+
+ -
+
+
-
+
+
source+ +
+
+
Runs before AutoCompleteBase's _createObjectSource() method and augments
+it to support additional object-based source types.
Parameters:
+ +-
+
+
-
+
+
source+ String + + + + ++ ++ + +
+
+
_bindUIACBase
+
+
+ ()
+
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Attaches event listeners and behaviors.
+_createArraySource
+
+
+ -
+
+
-
+
+
source+ +
+
+
Creates a DataSource-like object that simply returns the specified array as
+a response. See the source attribute for more details.
Parameters:
+ +-
+
+
-
+
+
source+ Array + + + + ++ ++ + +
+
+
Returns:
+ +_createFunctionSource
+
+
+ -
+
+
-
+
+
source+ +
+
+
Creates a DataSource-like object that passes the query to a custom-defined
+function, which is expected to call the provided callback with an array of
+results. See the source attribute for more details.
Parameters:
+ +-
+
+
-
+
+
source+ Function + + + + +++ + +Function that accepts a query and a callback as + parameters, and calls the callback with an array of results.
+
+
+
Returns:
+ +_createIOSource
+
+
+ -
+
+
-
+
+
source+ +
+
+
Creates a DataSource-like object that uses Y.io as a source. See the
+source attribute for more details.
Parameters:
+ +-
+
+
-
+
+
source+ String + + + + +++ + +URL.
+
+
+
Returns:
+ +_createJSONPSource
+
+
+ -
+
+
-
+
+
source+ +
+
+
Creates a DataSource-like object that uses the specified JSONPRequest
+instance as a source. See the source attribute for more details.
Parameters:
+ +-
+
+
-
+
+
source+ JSONPRequest | String + + + + +++ + +URL string or JSONPRequest instance.
+
+
+
Returns:
+ +_createObjectSource
+
+
+ -
+
+
-
+
+
source+ +
+
+
Creates a DataSource-like object that looks up queries as properties on the
+specified object, and returns the found value (if any) as a response. See
+the source attribute for more details.
Parameters:
+ +-
+
+
-
+
+
source+ Object + + + + ++ ++ + +
+
+
Returns:
+ +_createSelectSource
+
+
+ -
+
+
-
+
+
source+ +
+
+
Creates a DataSource-like object that uses the specified <select> node as
+a source.
Parameters:
+ +-
+
+
-
+
+
source+ Node + + + + +++ + +YUI Node instance wrapping a
+<select>node.
+
+
Returns:
+ +_createStringSource
+
+
+ -
+
+
-
+
+
source+ +
+
+
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.
Parameters:
+ +-
+
+
-
+
+
source+ String + + + + +++ + +URL or YQL query.
+
+
+
Returns:
+ +_createYQLSource
+
+
+ -
+
+
-
+
+
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.
Parameters:
+ +-
+
+
-
+
+
source+ String + + + + +++ + +YQL query.
+
+
+
Returns:
+ +_defaultYQLLocator
+
+
+ -
+
+
-
+
+
response+ +
+
+
Default resultListLocator used when a string-based YQL source is set and the +implementer hasn't already specified one.
+Parameters:
+ +-
+
+
-
+
+
response+ Object + + + + +++ + +YQL response object.
+
+
+
Returns:
+ +_defClearFn
+
+
+ ()
+
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Default clear event handler. Sets the results attribute to an empty
+array and query to null.
_defQueryFn
+
+
+ -
+
+
-
+
+
e+ +
+
+
Default query event handler. Sets the query attribute and sends a
+request to the source if one is configured.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_defResultsFn
+
+
+ -
+
+
-
+
+
e+ +
+
+
Default results event handler. Sets the results attribute to the latest
+results.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_functionValidator
+
+
+ -
+
+
-
+
+
value+ +
+
+
Returns true if value is either a function or null.
Parameters:
+ +-
+
+
-
+
+
value+ Function | Null + + + + +++ + +Value to validate.
+
+
+
_getObjectValue
+
+
+ -
+
+
-
+
+
obj+ +
+
+ -
+
+
path+ +
+
+
Faster and safer alternative to Y.Object.getValue(). Doesn't bother
+casting the path to an array (since we already know it's an array) and
+doesn't throw an error if a value in the middle of the object hierarchy is
+neither undefined nor an object.
Parameters:
+ + +Returns:
+ +undefined if the value was
+ not found at the specified path.
+
+ _getXHRUrl
+
+
+ -
+
+
-
+
+
url+ +
+
+ -
+
+
request+ +
+
+
Returns a formatted XHR URL based on the specified base url, query, and +the current requestTemplate if any.
+Parameters:
+ + +Returns:
+ +_jsonpFormatter
+
+
+ -
+
+
-
+
+
url+ +
+
+ -
+
+
proxy+ +
+
+ -
+
+
query+ +
+
+
URL formatter passed to JSONPRequest instances.
Parameters:
+ + +Returns:
+ +_onInputBlur
+
+
+ -
+
+
-
+
+
e+ +
+
+
Handles blur events on the input node.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_onInputValueChange
+
+
+ -
+
+
-
+
+
e+ +
+
+
Handles valueChange events on the input node and fires a query event
+when the input value meets the configured criteria.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_onResponse
+
+
+ -
+
+
-
+
+
e+ +
+
+
Handles source responses and fires the results event.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_parseResponse
+
+
+ -
+
+
-
+
+
query+ +
+
+ -
+
+
response+ +
+
+ -
+
+
data+ +
+
+
Parses result responses, performs filtering and highlighting, and fires the
+results event.
_parseValue
+
+
+ -
+
+
-
+
+
value+ +
+
+
Returns the query portion of the specified input value, or null if there
+is no suitable query within the input value.
If a query delimiter is defined, the query will be the last delimited part +of of the string.
+Parameters:
+ +-
+
+
-
+
+
value+ String + + + + +++ + +Input value from which to extract the query.
+
+
+
Returns:
+ +_setEnableCache
+
+
+ -
+
+
-
+
+
value+ +
+
+
Setter for the enableCache attribute.
Parameters:
+ +-
+
+
-
+
+
value+ Boolean + + + + ++ ++ + +
+
+
_setLocator
+
+
+ -
+
+
-
+
+
locator+ +
+
+
Setter for locator attributes.
+Returns:
+ +_setRequestTemplate
+
+
+ -
+
+
-
+
+
template+ +
+
+
Setter for the requestTemplate attribute.
Returns:
+ +_setResultFilters
+
+
+ -
+
+
-
+
+
filters+ +
+
+
Setter for the resultFilters attribute.
Parameters:
+ + +Returns:
+ +null).
+
+ _setResultHighlighter
+
+
+ -
+
+
-
+
+
highlighter+ +
+
+
Setter for the resultHighlighter attribute.
Parameters:
+ + +Returns:
+ +_setSource
+
+
+ -
+
+
-
+
+
source+ +
+
+
Setter for the source attribute. Returns a DataSource or a DataSource-like
+object depending on the type of source and/or the value of the
+sourceType attribute.
Parameters:
+ +-
+
+
-
+
+
source+ Any + + + + +++ + +AutoComplete source. See the
+sourceattribute for + details.
+
+
Returns:
+ +_sourceSuccess
+
+
+ -
+
+
-
+
+
data+ +
+
+ -
+
+
request+ +
+
+
Shared success callback for non-DataSource sources.
+Parameters:
+ +-
+
+
-
+
+
data+ Any + + + + +++ + +Response data.
+
+
+ -
+
+
request+ Object + + + + +++ + +Request object.
+
+
+
_syncBrowserAutocomplete
+
+
+ ()
+
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Synchronizes the UI state of the allowBrowserAutocomplete attribute.
_syncUIACBase
+
+
+ ()
+
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Synchronizes the UI state of the inputNode.
_updateValue
+
+
+ -
+
+
-
+
+
newVal+ +
+
+
Updates the query portion of the value attribute.
If a query delimiter is defined, the last delimited portion of the input +value will be replaced with the specified value.
+Parameters:
+ +-
+
+
-
+
+
newVal+ String + + + + +++ + +New value.
+
+
+
clearCache
+
+
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
+ chainable
+
+
+
+
+
+
+ Clears the result cache.
+sendRequest
+
+
+ -
+
+
-
+
+
[query]+ +
+
+ -
+
+
[requestTemplate]+ +
+
+
Sends a request to the configured source. If no source is configured, this +method won't do anything.
+ +Usually there's no reason to call this method manually; it will be called
+automatically when user input causes a query event to be fired. The only
+time you'll need to call this method manually is if you want to force a
+request to be sent when no user input has occurred.
Parameters:
+ +-
+
+
-
+
+
[query]+ String + optional + + + + +++ + +Query to send. If specified, the
+queryattribute + will be set to this query. If not specified, the current value of the +queryattribute will be used.
+
+ -
+
+
[requestTemplate]+ Function + optional + + + + +++ + +Request template function. If not + specified, the current value of the
+requestTemplateattribute will be + used.
+
+
Properties
+ + +_YQL_SOURCE_REGEX
+ RegExp
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ Regular expression used to determine whether a String source is a YQL query.
+SOURCE_TYPES
+ Object
+
+
+
+
+
+
+
+
+ static
+
+
+
+
+ Mapping of built-in source types to their setter functions. DataSource instances +and DataSource-like objects are handled natively, so are not mapped here.
+Attributes
+ + +allowBrowserAutocomplete
+ Boolean
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Whether or not to enable the browser's built-in autocomplete functionality +for input fields.
+Default: false
+ + + +Fires event allowBrowserAutocompleteChange
+
+
+ Fires when the value for the configuration attribute allowBrowserAutocomplete is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
allowTrailingDelimiter
+ Boolean
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ When a queryDelimiter is set, trailing delimiters will automatically be
+stripped from the input value by default when the input node loses focus.
+Set this to true to allow trailing delimiters.
Default: false
+ + + +Fires event allowTrailingDelimiterChange
+
+
+ Fires when the value for the configuration attribute allowTrailingDelimiter is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
enableCache
+ Boolean
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Whether or not to enable in-memory caching in result sources that support +it.
+Default: true
+ + + +Fires event enableCacheChange
+
+
+ Fires when the value for the configuration attribute enableCache is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
inputNode
+ Node | HTMLElement | String
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Node to monitor for changes, which will generate query events when
+appropriate. May be either an <input> or a <textarea>.
Fires event inputNodeChange
+
+
+ Fires when the value for the configuration attribute inputNode is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
maxResults
+ Number
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Maximum number of results to return. A value of 0 or less will allow an
+unlimited number of results.
Default: 0
+ + + +Fires event maxResultsChange
+
+
+ Fires when the value for the configuration attribute maxResults is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
minQueryLength
+ Number
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Minimum number of characters that must be entered before a query event
+will be fired. A value of 0 allows empty queries; a negative value will
+effectively disable all query events.
Default: 1
+ + + +Fires event minQueryLengthChange
+
+
+ Fires when the value for the configuration attribute minQueryLength is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
query
+ String | Null
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ readonly
+
+
+
+
+ Current query, or null if there is no current query.
The query might not be the same as the current value of the input node, both
+for timing reasons (due to queryDelay) and because when one or more
+queryDelimiter separators are in use, only the last portion of the
+delimited input string will be used as the query value.
Default: null
+ + + +Fires event queryChange
+
+
+ Fires when the value for the configuration attribute query is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
queryDelay
+ Number
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Number of milliseconds to delay after input before triggering a query
+event. If new input occurs before this delay is over, the previous input
+event will be ignored and a new delay will begin.
This can be useful both to throttle queries to a remote data source and to +avoid distracting the user by showing them less relevant results before +they've paused their typing.
+Default: 100
+ + + +Fires event queryDelayChange
+
+
+ Fires when the value for the configuration attribute queryDelay is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
queryDelimiter
+ String | Null
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Query delimiter string. When a delimiter is configured, the input value
+will be split on the delimiter, and only the last portion will be used in
+autocomplete queries and updated when the query attribute is
+modified.
Default: null
+ + + +Fires event queryDelimiterChange
+
+
+ Fires when the value for the configuration attribute queryDelimiter is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
requestTemplate
+ Function | String | Null
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Source request template. This can be a function that accepts a query as a
+parameter and returns a request string, or it can be a string containing the
+placeholder "{query}", which will be replaced with the actual URI-encoded
+query. In either case, the resulting string will be appended to the request
+URL when the source attribute is set to a remote DataSource, JSONP URL, or
+XHR URL (it will not be appended to YQL URLs).
While requestTemplate may be set to either a function or a string, it will
+always be returned as a function that accepts a query argument and returns a
+string.
Default: null
+ + + +Fires event requestTemplateChange
+
+
+ Fires when the value for the configuration attribute requestTemplate is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
resultFilters
+ Array
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Array of local result filter functions. If provided, each filter will be
+called with two arguments when results are received: the query and an array
+of result objects. See the documentation for the results event for a list
+of the properties available on each result object.
Each filter is expected to return a filtered or modified version of the
+results array, which will then be passed on to subsequent filters, then the
+resultHighlighter function (if set), then the resultFormatter function
+(if set), and finally to subscribers to the results event.
If no source is set, result filters will not be called.
Prepackaged result filters provided by the autocomplete-filters and
+autocomplete-filters-accentfold modules can be used by specifying the filter
+name as a string, such as 'phraseMatch' (assuming the necessary filters
+module is loaded).
Default: []
+ + + +Fires event resultFiltersChange
+
+
+ Fires when the value for the configuration attribute resultFilters is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
resultFormatter
+ Function | Null
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Function which will be used to format results. If provided, this function +will be called with two arguments after results have been received and +filtered: the query and an array of result objects. The formatter is +expected to return an array of HTML strings or Node instances containing the +desired HTML for each result.
+ +See the documentation for the results event for a list of the properties
+available on each result object.
If no source is set, the formatter will not be called.
Fires event resultFormatterChange
+
+
+ Fires when the value for the configuration attribute resultFormatter is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
resultHighlighter
+ Function | Null
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Function which will be used to highlight results. If provided, this function +will be called with two arguments after results have been received and +filtered: the query and an array of filtered result objects. The highlighter +is expected to return an array of highlighted result text in the form of +HTML strings.
+ +See the documentation for the results event for a list of the properties
+available on each result object.
If no source is set, the highlighter will not be called.
Fires event resultHighlighterChange
+
+
+ Fires when the value for the configuration attribute resultHighlighter is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
resultListLocator
+ Function | String | Null
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Locator that should be used to extract an array of results from a non-array +response.
+ +By default, no locator is applied, and all responses are assumed to be +arrays by default. If all responses are already arrays, you don't need to +define a locator.
+ +The locator may be either a function (which will receive the raw response as
+an argument and must return an array) or a string representing an object
+path, such as "foo.bar.baz" (which would return the value of
+result.foo.bar.baz if the response is an object).
While resultListLocator may be set to either a function or a string, it
+will always be returned as a function that accepts a response argument and
+returns an array.
Fires event resultListLocatorChange
+
+
+ Fires when the value for the configuration attribute resultListLocator is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
results
+ Array
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ readonly
+
+
+
+
+ Current results, or an empty array if there are no results.
+Default: []
+ + + +Fires event resultsChange
+
+
+ Fires when the value for the configuration attribute results is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
resultTextLocator
+ Function | String | Null
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Locator that should be used to extract a plain text string from a non-string +result item. The resulting text value will typically be the value that ends +up being inserted into an input field or textarea when the user of an +autocomplete implementation selects a result.
+ +By default, no locator is applied, and all results are assumed to be plain +text strings. If all results are already plain text strings, you don't need +to define a locator.
+ +The locator may be either a function (which will receive the raw result as
+an argument and must return a string) or a string representing an object
+path, such as "foo.bar.baz" (which would return the value of
+result.foo.bar.baz if the result is an object).
While resultTextLocator may be set to either a function or a string, it
+will always be returned as a function that accepts a result argument and
+returns a string.
Fires event resultTextLocatorChange
+
+
+ Fires when the value for the configuration attribute resultTextLocator is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
source
+ Array | DataSource | Function | Node | Object | String | Null
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Source for autocomplete results. The following source types are supported:
+ +-
+
- Array +
-
+
+ The full array will be provided to any configured filters for each + query. This is an easy way to create a fully client-side autocomplete + implementation. +
+ ++ Example:
+['first result', 'second result', 'etc']+
+
+ - DataSource +
-
+ A
DataSourceinstance or other object that provides a DataSource-like +sendRequestmethod. See theDataSourcedocumentation for details. +
+
+ - Function +
-
+
+ A function source will be called with the current query and a + callback function as parameters, and should either return an array of + results (for synchronous operation) or return nothing and pass an + array of results to the provided callback (for asynchronous + operation). +
+ ++ Example (synchronous): +
+ ++ function (query) { + return ['foo', 'bar']; + } ++ ++ Example (async): +
+ ++ function (query, callback) { + callback(['foo', 'bar']); + } ++
+
+ - Object +
-
+
+ An object will be treated as a query hashmap. If a property on the + object matches the current query, the value of that property will be + used as the response. +
+ ++ The response is assumed to be an array of results by default. If the + response is not an array, provide a
+ +resultListLocatorto + process the response and return an array. ++ Example:
+{foo: ['foo result 1', 'foo result 2'], bar: ['bar result']}+
+
If the optional autocomplete-sources module is loaded, then
+the following additional source types will be supported as well:
-
+
- <select> Node +
-
+ You may provide a YUI Node instance wrapping a <select>
+ element, and the options in the list will be used as results. You
+ will also need to specify a
resultTextLocatorof 'text' + or 'value', depending on what you want to use as the text of the + result. + + Each result will be an object with the following properties: + +-
+
- html (String) +
-
+
HTML content of the <option> element.
+
+
+ - index (Number) +
-
+
Index of the <option> element in the list.
+
+
+ - node (Y.Node) +
-
+
Node instance referring to the original <option> element.
+
+
+ - selected (Boolean) +
-
+
Whether or not this item is currently selected in the + <select> list.
+
+
+ - text (String) +
-
+
Text content of the <option> element.
+
+
+ - value (String) +
-
+
Value of the <option> element.
+
+
+
+ - String (JSONP URL) +
-
+
+ If a URL with a
+ +{callback}placeholder is provided, it will be used to + make a JSONP request. The{query}placeholder will be replaced with + the current query, and the{callback}placeholder will be replaced + with an internally-generated JSONP callback name. Both placeholders must + appear in the URL, or the request will fail. An optional{maxResults}+ placeholder may also be provided, and will be replaced with the value of + the maxResults attribute (or 1000 if the maxResults attribute is 0 or + less). ++ The response is assumed to be an array of results by default. If the + response is not an array, provide a
+ +resultListLocatorto process the + response and return an array. ++ The
+ +jsonpmodule must be loaded in order for + JSONP URL sources to work. If thejsonpmodule + is not already loaded, it will be loaded on demand if possible. ++ Example:
+'http://example.com/search?q={query}&callback={callback}'+
+
+ - String (XHR URL) +
-
+
+ If a URL without a
+ +{callback}placeholder is provided, it will be used + to make a same-origin XHR request. The{query}placeholder will be + replaced with the current query. An optional{maxResults}placeholder + may also be provided, and will be replaced with the value of the + maxResults attribute (or 1000 if the maxResults attribute is 0 or less). ++ The response is assumed to be a JSON array of results by default. If the + response is a JSON object and not an array, provide a +
+ +resultListLocatorto process the response and return an array. If the + response is in some form other than JSON, you will need to use a custom + DataSource instance as the source. ++ The
+ +io-baseandjson-parsemodules + must be loaded in order for XHR URL sources to work. If + these modules are not already loaded, they will be loaded on demand + if possible. ++ Example:
+'http://example.com/search?q={query}'+
+
+ - String (YQL query) +
-
+
+ If a YQL query is provided, it will be used to make a YQL request. The +
+ +{query}placeholder will be replaced with the current autocomplete + query. This placeholder must appear in the YQL query, or the request + will fail. An optional{maxResults}placeholder may also be provided, + and will be replaced with the value of the maxResults attribute (or 1000 + if the maxResults attribute is 0 or less). ++ The
+ +yqlmodule must be loaded in order for YQL + sources to work. If theyqlmodule is not + already loaded, it will be loaded on demand if possible. ++ Example:
+'select * from search.suggest where query="{query}"'+
+
As an alternative to providing a source, you could simply listen for query
+events and handle them any way you see fit. Providing a source is optional,
+but will usually be simpler.
Fires event sourceChange
+
+
+ Fires when the value for the configuration attribute source is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
sourceType
+ String
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ May be used to force a specific source type, overriding the automatic source +type detection. It should almost never be necessary to do this, but as they +taught us in the Boy Scouts, one should always be prepared, so it's here if +you need it. Be warned that if you set this attribute and something breaks, +it's your own fault.
+ +Supported sourceType values are: 'array', 'datasource', 'function', and
+'object'.
If the autocomplete-sources module is loaded, the following additional
+source types are supported: 'io', 'jsonp', 'select', 'string', 'yql'
Fires event sourceTypeChange
+
+
+ Fires when the value for the configuration attribute sourceType is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
tokenInput
+ Plugin.TokenInput
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ readonly
+
+
+
+
+ If the inputNode specified at instantiation time has a node-tokeninput
+plugin attached to it, this attribute will be a reference to the
+Y.Plugin.TokenInput instance.
Fires event tokenInputChange
+
+
+ Fires when the value for the configuration attribute tokenInput is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
value
+ String
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Current value of the input node.
+Default: ''
+ + + +Fires event valueChange
+
+
+ Fires when the value for the configuration attribute value is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
yqlEnv
+ String
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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).
Default: null
+ + + +Fires event yqlEnvChange
+
+
+ Fires when the value for the configuration attribute yqlEnv is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
yqlProtocol
+ String
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ URL protocol to use when the source is set to a YQL query.
Default: 'http'
+ + + +Fires event yqlProtocolChange
+
+
+ Fires when the value for the configuration attribute yqlProtocol is
+ changed. You can listen for the event using the on method if you
+ wish to be notified before the attribute's value has changed, or
+ using the after method if you wish to be notified after the
+ attribute's value has changed.
+
Parameters:
+ +-
+
-
+
e+ EventFacade + ++ An Event Facade object with the following + attribute-specific properties added: ++ +-
+
-
+
prevVal+ Any +The value of the attribute, prior to it being set.+
+ -
+
newVal+ Any +The value the attribute is to be set to.+
+ -
+
attrName+ String +The name of the attribute being set.+
+ -
+
subAttrName+ String +If setting a property within the attribute's value, the name of the sub-attribute property being set.+
+
+ -
+
Events
+ + +clear
+
+
+
+
+
+
+
+
+
+
+
+
+ Fires after the query has been completely cleared or no longer meets the +minimum query length requirement.
+query
+
+
+
+
+
+
+
+
+
+
+
+
+ Fires when the contents of the input field have changed and the input +value meets the criteria necessary to generate an autocomplete query.
+Event Payload:
+ +-
+
+
-
+
+
inputValue+ String + + + + +++ + +Full contents of the text input field or + textarea that generated the query.
+
+
+ -
+
+
query+ String + + + + +++ + +AutoComplete query. This is the string that will + be used to request completion results. It may or may not be the same + as
+inputValue.
+
+ -
+
+
src+ String + + + + +++ + +Source of the event.
+
+
+
results
+
+
+
+
+
+
+
+
+
+
+
+
+ Fires after query results are received from the source. If no source has +been set, this event will not fire.
+Event Payload:
+ +-
+
+
-
+
+
data+ Array | Object + + + + +++ + +Raw, unfiltered result data (if available).
+
+
+ -
+
+
query+ String + + + + +++ + +Query that generated these results.
+
+
+ -
+
+
results+ Object[] + + + + +++ + +Array of filtered, formatted, and highlighted + results. Each item in the array is an object with the following + properties:
+-
+
+
-
+
+
display+ Node | HTMLElement | String + + +++ + +Formatted result + HTML suitable for display to the user. If no custom formatter is + set, this will be an HTML-escaped version of the string in the +
+textproperty.
+
+ -
+
+
[highlighted]+ String + optional + + +++ + +Highlighted (but not + formatted) result text. This property will only be set if a + highlighter is in use.
+
+
+ -
+
+
raw+ Any + + +++ + +Raw, unformatted result in whatever form it + was provided by the source.
+
+
+ -
+
+
text+ String + + +++ + +Plain text version of the result, + suitable for being inserted into the value of a text input field + or textarea when the result is selected by a user. This value is + not HTML-escaped and should not be inserted into the page using +
+innerHTMLorNode#setContent().
+
+
+
+ -
+
+