ADF 11g – the native AutoSuggest behavior

The recent ADF 11gR1 PS1 release introduced a component we have been waiting for: the inputText with AutoSuggest. An inputText component that will present suggested values to the user depending on whatever text the user has already entered. The implementation in ADF of the functionality that got AJAX started, based on the original Google Suggest feature:

The auto suggest mechanism in ADF is not so much a new input component as it is a behavior (component) that can be added to inputText components. By adding the properly configured autoSuggest to an inputText, it is turned into an inputText with autoSuggest:

<af:inputText label="Country" value="#{item.country}"
              columns="20" id="it5">
  <af:autoSuggestBehavior suggestedItems="#{countrySuggester.getCountries}"/>
</af:inputText>

Here we have added the autoSuggestBehavior to an inputText that is used for entering a country. Of course we could have used a dropdown component, combobox or list of values. However, the auto suggest is somewhat more light weight and elegant especially when our collection of countries is far from complete, and we only have a limited number of suggestions to offer – and we certainly would not want to suggest that the user can only choose from the values we are proposing.

When the input text has focus, a list of suggested values is presented. As soon as the user has typed a character, a filtered list of suggested values is presented. Well, that seems the obvious thing to do. However: what items are presented as suggested values is entirely up to us! The autoSuggestBehavior component is really nothing but a fairly fancy UI component. It does not filter, sort, suggest etc on its own accord. Everything that has to do with what values are suggested, how many of them and in what order must be programmed by us ourselves, in the method referred to by the attribute suggestedItems. If you only want to show suggestions when the user has typed at least 3 characters: again, you write that logic into the suggesteditems method.

The autoSuggestBehavior can be used whenever and wherever an inputText component can be used, for example inside a table:

Or inside a Carousel:

Note that the list of suggested values supports:

• traversing the list by using the up and down arrow, starting with down arrow when the focus is still on the inputText component (it does not wrap around – i.e. when on the last item, typing down does nothing; it does not make the first item in the suggested values list the selected on)
• selecting a suggested value from the list (either with mouse or enter key) and thus applying that value to the inputText component

Also note that since we control whatever values are shown in the suggested values list, we probably can find slightly alternative ways of using this functionality whereby the suggested values are not necessarily based on the alphabetic filtering of a predefined list based on the exact string entered by the user.

Implementing Auto Suggest Behavior

The only thing we need to do in order to implement the auto suggest functionality, apart from adding the autoSuggestBehavior tag to the inputText component of choice, is implement the method that returns the the suggested values. This method needs to have this signature:

 public List<SelectItem> methodName(String currentValueInInputText)

This method is entirely responsible for determining the values to be presented, the number of them, the order of them etc.

The suggested list of countries is produced by the countrySuggester bean:

public class CountrySuggester {

  private List<SelectItem> countries = new ArrayList<SelectItem>();

  public CountrySuggester() {
    countries.add(new SelectItem("Belgium"));
    countries.add(new SelectItem("Bulgaria"));
    ...
  }

  public List<SelectItem> getCountries(String country) {
    //todo
    List<SelectItem> items = new ArrayList<SelectItem>();
    for(SelectItem item:countries){
      if (item.getLabel().startsWith(country)) {
        items.add(item);
      }
    }
    return items;
  }
}

Resources

Download JDeveloper Fusion Application: DemoAppWithAutoSuggest.