Around the web we can find a lot of interesting e useful flex custom components. In my last works I had the chance to use the Autocomplete component developed by Hillel Coren (http://hillelcoren.com). In this post I'll try to present it briefly.
Customizing behavior and interface of the component :
This component is very similar to a standard ComboBox, although it doesn't extend from that kind of flex UIComponent. It has a fair number settings you can adjust, like:
- selectedItemsStyleName: through this property, developers can control the look of selected items. There are four choices: facebook, macMail, underline and none
- prompt: using this property you can set a string the component will display when no value is set.
- ackSpaceAction: this property determines what to do when a user press backspace. By default the component focus the item, but this can be changed to remove it.
- enableClearIcon: this boolean property, if set to true, make the component to display a little cross icon that allow users to clean the search field of the component.
Customizing drop down aspect
We can control how the item is displayed through out the component setting the labelField or the labelFunction property, like in most other Flex components. AutoComplete has two other properties we can use for customizing the drop down label:
- dropDownLabelFunction: which returns an HTML string to handle formatting the item;
- dropDownItemRenderer: if you like greater control over the layout.
Multiple selections and events
If the boolean property allowMultipleSelection is set to “true”, the component allows user to select more than one item. So the AutoComplete can contain selected items and the search string. Access to all these elements is granted by two properties:
- searchText: this property can be used to get/set the search string.
- text : this property returns a string representation of the selected items.
Related to this there are two main events which the component dispatches: change and searchChange. The change event is dispatched when the selectedItem property changes, while the searchChange event is dispatched when the search string is changed.
Filtering the data
To filter the data you can use the built-in options by setting the “matchType” property; the built-in options are:
- beginning: Only match the beginning of the string.
- word: Match the beginning of any of the words in the string.
- anyPart: Matches any part of the string.
You can also create a custom filter by setting a value for the filterFunction property.
Example Application
I used the AutoComplete component in the “search area” of an application, to supply users with a better experience in navigating data and searching information. It's also very useful in filtering collections of data ( and complex data) represented by listComponent. To demonstrate this I wrote a simple example application in which users can use the autoComplete component to filter the entries of a data grid containing information about people, represented with “name”, “last name” and an “email” address.
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="horizontal"
xmlns:hc="com.hillelcoren.components.*">
<mx:Script>
<![CDATA[
import mx.collections.ArrayCollection;
import com.hillelcoren.utils.StringUtils;
import com.hillelcoren.components.AutoComplete;
private function labelFunction(item:Object):String
{
var str:String = item["name"] +" "+item["lastname"]+ " < "+item["email"]+" >";
return str;
}
private function filterFunction( item:Object, searchStr:String ):Boolean
{
if (searchStr.length == 0)
{
return true;
}
var str:String = labelFunction(item);
switch (autoComplete.matchType)
{
case AutoComplete.MATCH_ANY_PART:
return StringUtils.contains( str, searchStr );
case AutoComplete.MATCH_BEGINNING:
return StringUtils.beginsWith( str, searchStr );
case AutoComplete.MATCH_WORD:
return StringUtils.anyWordBeginsWith( str, searchStr );
}
return false;
}
]]>
</mx:Script>
<mx:ArrayCollection id="dataProvider">
<mx:Array id="dataArray">
<mx:Object name="Peter" lastname="Griffin" email="p.griffin@gmail.com"/>
<mx:Object name="Mario" lastname="Brega" email="m.brega@gmail.com"/>
<mx:Object name="Homer" lastname="Simpson" email="h.simpson@yahoo.com"/>
<mx:Object name="Clark" lastname="Kent" email="c.kent@gmail.com"/>
<mx:Object name="Lex" lastname="Luthor" email="l.luthor@gmail.com"/>
<mx:Object name="Peter" lastname="Parker" email="p.parker@yahoo.com"/>
<mx:Object name="Ned" lastname="Flanders" email="n.flanders@gmail.com"/>
<mx:Object name="Lois" lastname="Lane" email="l.lane@gmail.com"/>
<mx:Object name="John" lastname="Zoidberg" email="j.zoidberg@yahoo.com"/>
</mx:Array>
</mx:ArrayCollection>
<hc:AutoComplete id="autoComplete" dataProvider="{this.dataProvider}"
width="35%"
labelFunction="labelFunction"
enableClearIcon="true"
prompt="Type in name or lastname or email"
filterFunction="filterFunction" />
<mx:Spacer width="10%"/>
<mx:DataGrid id="dataGrid" dataProvider="{this.dataProvider}"
width="40%" />
</mx:Application>
To obtain the correct behavior I customized the functions labelFunction and filterFunction. I needed to rewrite the first function to group the three fields in a single string, that is then used by the second function to filter data using the string representation of those fields. In this way users are allowed to search people in the datagrid, by name, by lastname or email, typing in the search string using one single autoComplete component.
This custom component could be very useful also in input forms, as “smart TextInput” component. Unfortunately in this context this AutoComplete component has a little lack. It has been designed to select one item (or more) from an existing collection, but not to insert new items. The allowNewValues property allows user to insert new values in the search field, but not in the collection set as dataProvider of the AutoComplete. Moreover it is not possible to write in the search text values that have as prefixes strings representing items already in the dataprovider collection. For example: it is not possible to write “Alexander” in the search text if in the data provider there is already an item represented by the string “Alex”. Trying to type-in “Alexander” will automatically select “Alex” at the fourth character.
More information available about the component can be found within its documentation: http://web.me.com/hillelcoren/Site/AutoComplete.html