The ICEfaces Tutorial
Table of Contents


Lesson: Using the autocomplete component

How to Use the ICEfaces Auto-Complete Component

The auto-complete component is actually the ice:selectInputText component. This component provides an input text component enhanced with auto-complete functionality. As the user enters text into the component it provides a pop-up list of possible matching values that the user may select from.

The component predicts a word of phrase that a user wants to type in without the user actually completely typing it in. The component requires developers to implement the matching search algorithm in the backing bean.

For this tutorial a simple application has been developed. The application consists of a text box for cities in the United States of America.

Auto Complete Application

This tutorial will discuss the following topic related to the use of the auto-complete/selectInputText component:

Download the demo:

 

Adding the Component

To get auto-complete functionality we will use the selectInputText component. This component is displayed like a regular input text component but adds the ability to auto-complete the text.

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

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

The following code sample is how to use the component to generate 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 inputed. 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 links to a backing bean that controls the changing of the associated list when a value is changed.

Embedded in the selectInputText component tag is a selectItems JSF tag. This is the link to the backing beans list of available options. The screen shot below shows the component in action:

Auto Complete Application in Action

The following code sample is how to use the component to generate a list of arbitrary 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 addtion to the city. The screen shot below shows this method in action:

Auto Complete Application Child Components
 

Create the Backing Beans

For our example application we use cities but you can use anything that you want auto-completed in a form. In the application we use three main backing beans:

How each classes methods and what attributes each one will have will be dependent on what information will be used and what you wish to accomplish with your application.

 

Create the Dictionary

For the auto-complete component to work the application must have a dictionary that the backing beans can look at and get an appropriate list of viable options. The creation of this should follow a similar format as shown below:

          <java version="1.4.2_08" 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>
      

Each option you want available for the user needs to be added, for this reason the file can get fairly large and therefore we zip the xml file to help reduce the space taken up by the file. As with the beans the contents of the file may differ depending on what you need.

 

Example That Uses Auto-Complete

Example Source Notes
autocomplete-tutorial autocomplete-tutorial source code Simple example on how to use the Auto-Complete component.

The ICEfaces Tutorial
Table of Contents

Copyright 2006 ICEsoft Technologies Inc. All rights reserved.