How to Use the ICEfaces Auto-Complete Component

The auto-complete component is named ice:selectInputText. It provides an inputText component enhanced with the ability to select an option before input has been completed. As the user enters text into the component a pop-up list of possible matching values is provided to the user.

The component requires developers to implement a matching search algorithm in the backing bean. This algorithm provides results based on partial user input.

This tutorial consists of a simple application with a text box for entering a city in the United States of America.

Adding the Component

To get auto-complete functionality we use the ice:selectInputText component. This component is displayed like a regular inputText component but adds auto-complete functionality.

The ice:selectInputText component can generate one of two types of lists:

1. A list of String data
2. A list of arbitrarily complex child components

The following code sample shows an implementation using a list of String data:

<ice:selectInputText rows="10" width="300" valueChangeListener="#{autoCompleteBean.updateList}">
    <f:selectItems value="#{autoCompleteBean.list}"/>
</ice:selectInputText>

This will display a drop-down list of cities that match the text input. The 'rows' attribute defines how many results will be returned when text is entered. The 'width' attribute sets the width of the input text box and the drop-down list. The 'valueChangeListener' attribute binds to a backing bean method that determines the associated list when a value is changed.

Nested in the ice:selectInputText component tag is an f:selectItems JSF tag. The 'value' binding in this tag provides the list of available options. The screen shot below shows the component in action:

The following code sample shows an implementation with a list of arbitrarily complex child components:

<ice:selectInputText rows="6" 
                     width="300"
                     listVar="city"
                     valueChangeListener="#{autoCompleteBean.updateList}"
                     listValue="#{autoCompleteBean.list}">
    <f:facet name="selectInputText">
        <ice:panelGrid columns="3" 
                       style="margin-bottom:-20px;"
                       columnClasses="cityCol,stateCol,zipCol">
            <ice:outputText value="#{city.city}"/>
            <ice:outputText value="#{city.state}"/>
            <ice:outputText value="#{city.zip}"/>
        </ice:panelGrid>
    </f:facet>
</ice:selectInputText>

This will display values similar to the first way but adds more information to the drop down menu, such as state and zip, in addition to the city. The screen shot below shows this method in action:

Create the Backing Beans

In the application we use three main backing beans:

• AutoCompleteBean: Stores the values gathered from the AutoCompleteDictionary class. Also contains utility methods for updating the list and getting the matches from the dictionary list.
• AutoCompleteDictionary: Gets the dictionary list from a file in the file system. Also sorts the dictionary appropriately.
• City: Basic class used as an object in the dictionary list.
  
  

  ---

Create the Dictionary

The backing beans retrieve lists of viable options from AutoCompleteDictionary. Our dictionary is populated from an xml file as follows:

<java version="1.6.0_21" class="java.beans.XMLDecoder"> 
  <object class="java.util.ArrayList"> 
    <void method="add"> 
      <object class="com.icesoft.icefaces.tutorial.component.autocomplete.City"> 
        <void property="areaCode"> 
          <string>631</string> 
        </void> 
        <void property="city"> 
          <string>Holtsville</string> 
        </void> 
        <void property="country"> 
          <string>Suffolk</string> 
        </void> 
        <void property="state"> 
          <string>New York</string> 
        </void> 
        <void property="stateCode"> 
          <string>NY</string> 
        </void> 
        <void property="zip"> 
          <string>00501</string> 
        </void> 
      </object> 
    </void> 
  </object>
</java>

In this case, we have encapsulated the options available to the user in a zipped xml file that is deployed with the applications. Options available to the user could also be retrieved from a database.

Tutorial Source Code Downloads