com.databasesandlife.util.wicket
Class MultipleValueAutoCompleteTextField

java.lang.Object
  extended by com.databasesandlife.util.wicket.MultipleValueAutoCompleteTextField

public class MultipleValueAutoCompleteTextField
extends Object

A text-field where the user may enter multiple values, but each value may only be one of a pre-defined list of values. Similar to Facebook's message compose screen, where users may only enter recipients who are in their address book.

    

If the user should be allowed to enter values which are not in the pre-defined list of values (e.g. the "To:" field in Gmail, where email addresses are suggested, but any email address may be entered), see MultipleValueAutoSuggestTextField.

The list of values that are allowed may either be client-side (meaning they are specified at the time the text field is created, and are placed in the generated HTML) or they may be server-side (meaning the application must specify a callback, which is called each time the user starts to enter something, and which must return a list of values matching what the user has entered). The former is appropriate for smaller lists, as it is faster (no server round-trip), the latter for larger lists (as otherwise the generated HTML would be too large.)

Each value may have an internal ID and an external string that the user sees. The model of the field is a list of the internal IDs. The data source for the suggestions (either client-side or server-side) is an ordered list of ID and displayable string pairs. IDs are strings (but that doesn't stop them being string representations of numbers, of course).

Usage:

  <!-- In HTML -->
  <!-- Include JQuery, JQuery UI-->
  <link rel="stylesheet" type="text/css" ....> <-- From JQuery UI themeroller >
  <input type="text" wicket:id="languages"></input>

  // In Java
  MultipleValueAutoCompleteTextField f =
      new MultipleValueAutoCompleteTextField("languages");
  f.allowDuplicates(); // default is not to allow duplicates
  f.setClientSideOptions(new AutoCompleteOption[] {
      new AutoCompleteOption("en", "English"),
      new AutoCompleteOption("de", "German"),
  });  // or...
  f.setServerSideDataSource(new AutoCompleteDataSource() {
      AutoCompleteOption[] suggestOptions(String userEnteredText) {
          return ....;
      }
  });
  form.add(f);

By default the values (e.g. "English") are plain text strings. If you want to use HTML effects (e.g. have a few <span>s inside the value, with different styles), then subclass AutoCompleteOption and override getHtmlDisplayText. Due to the way the JS is programmed, use <font class="x"> as opposed to <span class="x">.

The text field is always on a separate line, this is a consequence of the Javascript library used, and seemed to be the case for all other Javascript libraries I saw as well. The solution, in case you want to have the text field on a line with a field name such as "To:", is either to use absolute positioning, or use tables.

If there is an error about a missing </span> tag, make sure the <input> tag is closed with a </input>, even though HTML would not normally require it to be closed. This is a consequence of an implementation issue.

The Javascript software used is jQuery Tokeninput.

Bugs

Version:
$Revision: 4247 $
Author:
The Java source is copyright Adrian Smith and licensed under the LGPL 3.

Constructor Summary
MultipleValueAutoCompleteTextField()
           
 
Method Summary
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MultipleValueAutoCompleteTextField

public MultipleValueAutoCompleteTextField()