How to use the Feathers AutoComplete
component
The AutoComplete
class extends the TextInput
component to add a pop-up list of suggestions as you type.
The Basics
First, let's create an AutoComplete
control and add it to the display list:
var input:AutoComplete = new AutoComplete();
this.addChild( input );
At this point, the AutoComplete
will behave like a normal TextInput
without suggestions. All properties available to a TextInput
(like maxChars
or prompt
, for example) may be used with an AutoComplete
too.
Providing suggestions for completion
An IAutoCompleteSource
implementation should be passed to the source
property to display suggestions for completion. Let's look at a couple of the classes that we can use to provide these suggestions.
LocalAutoCompleteSource
The simplest option involves passing a ListCollection
to LocalAutoCompleteSource
. As the user types, the collection will be filtered to display appropriate suggestions.
input.source = new LocalAutoCompleteSource( new ListCollection(new <String>
[
"Apple",
"Banana",
"Cherry",
"Grape",
"Lemon",
"Orange",
"Watermelon"
]));
When one types "ap" into the AutoComplete
, the list of suggestions will include "Apple" and "Grape". By default, LocalAutoCompleteSource
converts each item to lowercase, and it returns any item that contains the entered text. The entered text may be in the middle of an item, as we see when "ap" matches "Grape".
If the default behavior doesn't quite fit our needs, we can use a custom compareFunction
to handle the filtering. In the following example, we create a compareFunction
where the entered text must be at the very beginning of the suggestion:
var source:LocalAutoCompleteSource = new LocalAutoCompleteSource();
source.compareFunction = function( item:Object, textToMatch:String ):Boolean
{
return item.toString().toLowerCase().indexOf(textToMatch.toLowerCase()) == 0;
};
In this case, if one types "ap" using the same data provider as in the previous example, only "Apple" will be suggested. "Grape" will not be suggested because "ap" appears in the middle of the word instead of the beginning.
As you can see above, the first argument to the compareFunction
is typed as Object
, meaning that suggestions don't necessarily need to be strings.
URLAutoCompleteSource
In some cases, you may want to request personalized suggestions from a server instead. We can pass the text entered by the user to a backend API using URLAutoCompleteSource
.
To load suggestions from the web, we need a URL. The urlRequestFunction
property can be used to generate a URLRequest
:
var source:URLAutoCompleteSource = new URLAutoCompleteSource();
source.urlRequestFunction = function( textToMatch:String ):URLRequest
{
var request:URLRequest = new URLRequest( "http://example.com/search_suggestions" );
var variables:URLVariables = new URLVariables();
variables.query = textToMatch;
request.data = variables;
return request;
};
input.source = source;
The urlRequestFunction
takes one argument, the text entered into the AutoComplete
. We can pass that to the server to return relevant suggestions.
By default, URLAutoCompleteSource
parses the result as a JSON array. If the result returned by the API looks similar to the example below, it can be parsed automatically:
[
"adobe",
"adobe flash",
"adobe reader",
"adobe creative cloud"
]
However, if the API returns data in a different format, we can use the parseResultFunction
property to tell the URLAutoCompleteSource
how to convert the result into something that the pop-up list of suggestions can display.
Let's create a parseResultFunction
for some XML in the following format:
<search>
<suggestion>adobe</suggestion>
<suggestion>adobe flash</suggestion>
<suggestion>adobe reader</suggestion>
<suggestion>adobe creative cloud</suggestion>
</search>
In the custom parseResultFunction
below, we loop through each <suggestion>
element in the result and extract the string. We'll return an Array
of these strings:
source.parseResultFunction = function( result:String ):Object
{
var parsedSuggestions:Array = [];
var xmlResult:XML = new XML( result );
var resultCount:int = xmlResult.suggestion.length();
for( var i:int = 0; i < resultCount; i++ )
{
var suggestion:XML = xmlResult.suggestion[i];
parsedSuggestions.push( suggestion.toString() );
}
return parsedSuggestions;
};
The parseResultFunction
may return any type of object that may be passed to a ListCollection
, such as an Array
or a Vector
.
Customizing suggestion behavior
The minimumAutoCompleteLength
property determines how many characters must be entered into the input before displaying suggestions:
input.minimumAutoCompleteLength = 3;
By default, the input will not make suggestions until at least 2
characters have been typed.
The autoCompleteDelay
property determines how long to wait after the text in the input has been edited before updating the suggestions:
input.autoCompleteDelay = 0.25;
This value is measured in seconds, and the default value is 0.5
.
Skinning an AutoComplete
An AutoComplete
provides a number of properties to customize its appearance. For full details about what skin and style properties are available, see the AutoComplete
API reference.
As mentioned above, AutoComplete
is a subclass of TextInput
. For more detailed information about the skinning options available to AutoComplete
, see How to use the Feathers TextInput
component.
Targeting an AutoComplete
in a theme
If you are creating a theme, you can set a function for the default styles like this:
getStyleProviderForClass( AutoComplete ).defaultStyleFunction = setAutoCompleteStyles;
If you want to customize a specific AutoComplete
to look different than the default, you may use a custom style name to call a different function:
input.styleNameList.add( "custom-auto-complete" );
You can set the function for the custom style name like this:
getStyleProviderForClass( AutoComplete )
.setFunctionForStyleName( "custom-auto-complete", setCustomAutoCompleteStyles );
Trying to change the auto complete's styles and skins outside of the theme may result in the theme overriding the properties, if you set them before the AutoComplete
was added to the stage and initialized. Learn to extend an existing theme to add custom skins.
If you aren't using a theme, then you may set any of the auto complete's properties directly.