Autocompleter

Parameters
Examples

Implementation of autocomplete pull-down behaviour driven by ajax search requests. This implementation uses script.aculo.us Autocompleter client-side libraries to perform the majority of it's work.

For more information about the javascript library usage of Autocompleter please refer to the script.aculo.us documentation.

Note

The Autocompleter component renders its own form input field and it supports the translator and validators bindings of tapestry's TextField.

Parameters

Name	Type	Direction	Required	Default	Description
listener	IActionListener	in	no		Listener method to invoke for each field search request. This listener should expect to get at least one parameter of type String, which is the value that the request is searching on. Additional parameters will be included if the 'parameters' parameter is used. If no listener is specified, the autocompleter will work in clientOnly mode.
parameters	Object or Object[] or List	in	no		An array of objects to be encoded into the URL. These parameters will be decoded when the autocompleter is triggered and passed to the listener method. Note that the first parameter passed to the listener will always be the 'search string' - the parameters defined here will follow.
frequency	double	in	no	0.2	The amount of time (in seconds) that the component will wait before submitting new input changes to the server.
afterUpdateElement	String	in	no		Hook for the function called after the element has been updated (i.e. when the user has selected an entry). The function receives two parameters, the autocompletion input field and the selected item (the item selected). Deprecated, use the 'options' parameter.
listSource	Object, String[], or Collection	in	yes		Values to be used to autocomplete a particular autocomplete field search, this should be set when this component invokes your input search listener.
clientOnly	boolean	in	no	false	If true, generates an array of autocompletion options, and so all possible values are included in the html file. No further (ajax) requests are made. Note This is now deprecated. The autocompleter will automatically work in clientOnly mode if no listener is specified.
stateful	boolean	in	no	false	Whether or not the request created by this component should be required to be stateful or not, default is false.
direct	boolean	in	no	false	Specifies whether or not to do a direct service call for component. This will improve the performance of the call dramatically, but will probably produce tons of exceptions and problems if the component is embedded in other components, or contained in a loop.
listItemRenderer	ListItemRenderer	in	yes	DefaultListItemRenderer	The ListItemRenderer that should be used to render the drop down list, the default renderer iterates over the values and puts the string value in a <li></li> block.
maxResults	int	in	no		How many results to present at the most.
elementclass	String	in	no	auto_complete	The css class to use to render the drop down list.
options	string	in	no		Options to be passed directly to the javascript constructor of this control. Use json syntax. For instance: {tokens:' ', minChars:3}
value	string	in / out	yes		The value to be editted, which is is usually a string. Tapestry has limited ability to convert to and from strings.
disabled	boolean	in	no	false	If true, then a disabled attribute will be rendered as part of the <input> tag, and the component will not update its value parameter when the form is submitted.
displayName	string	in	no		The user-presentable name for the component, which will be used by a FieldLabel; connected to the component.
validators	string	in	no		The new validator binding, ie: "validators:required,minLength=4".
translator	string	in	no		The new translator binding, ie: "translator:date,required".

Body: rendered

Informal parameters: allowed

Reserved parameters:

Examples

This example shows an autocompleter that displays a list of Countries to choose from based on the Locale of the jvm running the application.

HTML template

          
<div id="notes">
<style>
  div.auto_complete {
    width: 350px;
    background: #fff;
  }
  div.auto_complete ul {
    border:1px solid #888;
    margin:0;
    padding:0;
    width:100%;
    list-style-type:none;
  }
  div.auto_complete ul li {
    margin:0;
    padding:3px;
  }
  div.auto_complete ul li.selected {
    background-color: #ffb;
  }
  div.auto_complete ul strong.highlight {
    color: #800;
    margin:0;
    padding:0;
  }
</style>

<div class="note" >
<h2>Country Search</h2>
    <form jwcid="@Form" >
        <input jwcid="textNote" type="text" size="42"/>
        <span class="auto_complete" jwcid="autoCompleter" />
    </form>
</div>
</div>

Page specification

          
<page-specification class="net.sf.tacos.demo.pages.ajax.AutocompleteExample">

<description>
  Partial Page Rendering example with forms
  </description>

<property name="noteValue" persist="session" />
<property name="searchList"
      initial-value="ognl:new java.util.ArrayList()" />
<property name="localeList"
      initial-value="ognl:new java.util.ArrayList()" />

<component id="textNote" type="TextField">
  <binding name="displayName">Note</binding>
  <binding name="value" value="ognl:noteValue"/>
  <binding name="autocomplete" value="literal:off" />
</component>

<component id="autoCompleter" type="tacos:Autocompleter" >
  <binding name="inputId" value="literal:textNote" />
  <binding name="listSource" value="ognl:searchList" />
  <binding name="listener" value="listener:searchCountries" />
</component>

<bean name="delegate"
      class="org.apache.tapestry.valid.ValidationDelegate"/>

<bean name="textValidator"
      class="org.apache.tapestry.valid.StringValidator">
  <set name="required" value="true"/>
</bean>

</page-specification>

Java sources

          
public abstract class AutocompleteField extends BasePage {

  /** Logger */
  private static final Log log =
      LogFactory.getLog(AutocompleteField.class);
  /** List html renderer */
  private static final ListItemRenderer FLAG_RENDERER =
      new CountryFlagRenderer();

  public ListItemRenderer getListRenderer()
  {
      return FLAG_RENDERER;
  }

  public void storeNote(IRequestCycle cycle) {
    IValidationDelegate delegate =
            (IValidationDelegate)getBeans().getBean("delegate");
    if (delegate.getHasErrors()) {
      return;
    }
  }

  /**
   * Invoked by ajax request to perform autocomplete
   * search.
   *
   * @param search The value to search on
   */
  public void searchCountries(String search)
  {
      log.debug("searchCountries(" + search + ")");

      //Performs country name search
      search = search.toUpperCase();
      Locale[] locales = Locale.getAvailableLocales();
      ArrayList searchList = new ArrayList();
      ArrayList localeList = new ArrayList();
      for (int i = 0; i < locales.length; i++) {
          if (locales[i].getDisplayCountry()
              .toUpperCase().indexOf(search) > -1) {
              searchList.add(locales[i].getDisplayCountry());
              localeList.add(locales[i]);
          }
      }

      setSearchList(searchList);
      setLocaleList(localeList);
  }

  /** Set by invocation of {@link #searchCountries(String)} */
  public abstract Collection getSearchList();
  /** Sets the search list return */
  public abstract void setSearchList(Collection values);
  /** Set by invocation of {@link #searchCountries(String)} */
  public abstract Collection getLocaleList();
  /** Sets the search list return */
  public abstract void setLocaleList(Collection values);
  /** form note value */
  public abstract String getNoteValue();
}