org.apache.click.extras.control
Class AutoCompleteTextField

java.lang.Object
  extended by org.apache.click.control.AbstractControl
      extended by org.apache.click.control.Field
          extended by org.apache.click.control.TextField
              extended by org.apache.click.extras.control.AutoCompleteTextField
All Implemented Interfaces:
Serializable, Control

public abstract class AutoCompleteTextField
extends TextField

Provides an Auto Complete Text Field control:   <input type='text'>.

Text Field

AutoCompleteTextField Example

The example below shows how to a create an AutoCompleteTextField. Note how the abstract method getAutoCompleteList() is implemented to provide the list of suggested values.
 AutoCompleteTextField nameField = new AutoCompleteTextField("name") {
     public List getAutoCompleteList(String criteria) {
         return getCustomerService().getCustomerNamesLike(criteria);
     }
 };
 form.add(nameField); 

CSS and JavaScript resources

AutoCompleteTextField depends on the Prototype and Scriptaculous/ JavaScript libraries to handle the auto-complete functionality. See Ajax.Autocompleter for more details.

The AutoCompleteTextField control makes use of the following resources (which Click automatically deploys to the application directory, /click):

See also the W3C HTML reference: INPUT

See Also:
Serialized Form

Field Summary
protected  String autoCompleteOptions
          The JavaScript 'script.aculo.us' Autocompleter initialization options, default value is: {minChars:1}.
 
Fields inherited from class org.apache.click.control.TextField
maxLength, minLength, size, VALIDATE_TEXTFIELD_FUNCTION
 
Fields inherited from class org.apache.click.control.Field
disabled, error, focus, form, help, label, labelStyle, labelStyleClass, parentStyleClassHint, parentStyleHint, readonly, required, tabindex, title, trim, validate, value
 
Fields inherited from class org.apache.click.control.AbstractControl
actionListener, attributes, headElements, listener, listenerMethod, messages, name, parent, styles
 
Fields inherited from interface org.apache.click.Control
CONTROL_MESSAGES
 
Constructor Summary
AutoCompleteTextField()
          Create a AutoCompleteTextField with no name defined.
AutoCompleteTextField(String name)
          Construct the AutoCompleteTextField with the given name.
AutoCompleteTextField(String name, boolean required)
          Construct the AutoCompleteTextField with the given name and required status.
AutoCompleteTextField(String name, String label)
          Construct the AutoCompleteTextField with the given name and label.
AutoCompleteTextField(String name, String label, boolean required)
          Construct the AutoCompleteTextField with the given name, label and required status.
AutoCompleteTextField(String name, String label, int size)
          Construct the AutoCompleteTextField with the given name, label and size.
 
Method Summary
abstract  List getAutoCompleteList(String criteria)
          Return the list of suggested values for the given search criteria.
 String getAutoCompleteOptions()
          Return the JavaScript 'script.aculo.us' Autocompleter initialization options, default value is: {}.
 List<Element> getHeadElements()
          Return the list of HEAD elements (resources) to be included in the page.
 void onInit()
          Register the field with the parent page to intercept POST autocompletion requests.
 boolean onProcess()
          Process the page request and if an auto completion POST request then render an list of suggested values.
 void render(HtmlStringBuffer buffer)
          Render the HTML representation of the AutoCompleteTextField.
protected  void renderAutoCompleteList(List<String> autoCompleteList)
          Render the suggested auto completion list to the servlet response.
 void setAutoCompleteOptions(String options)
          Set the JavaScript 'script.aculo.us' Autocompleter initialization options, default value is: {minChars:1}.
 void setParent(Object parent)
           
 
Methods inherited from class org.apache.click.control.TextField
getControlSizeEst, getMaxLength, getMinLength, getSize, getTag, getType, getValidationJavaScript, setMaxLength, setMinLength, setSize, validate
 
Methods inherited from class org.apache.click.control.Field
bindRequestValue, getError, getErrorLabel, getFocus, getFocusJavaScript, getForm, getHelp, getId, getLabel, getLabelStyle, getLabelStyleClass, getParentStyleClassHint, getParentStyleHint, getRequestValue, getTabIndex, getTextAlign, getTitle, getValidate, getValue, getValueObject, getWidth, isDisabled, isHidden, isReadonly, isRequired, isTrim, isValid, setDisabled, setError, setErrorMessage, setErrorMessage, setFocus, setForm, setHelp, setLabel, setLabelStyle, setLabelStyleClass, setListener, setParentStyleClassHint, setParentStyleHint, setReadonly, setRequired, setTabIndex, setTextAlign, setTitle, setTrim, setValidate, setValue, setValueObject, setWidth
 
Methods inherited from class org.apache.click.control.AbstractControl
addStyleClass, appendAttributes, dispatchActionEvent, getActionListener, getAttribute, getAttributes, getContext, getHtmlImports, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasStyles, onDeploy, onDestroy, onRender, removeStyleClass, renderTagBegin, renderTagEnd, setActionListener, setAttribute, setId, setName, setStyle, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

autoCompleteOptions

protected String autoCompleteOptions
The JavaScript 'script.aculo.us' Autocompleter initialization options, default value is: {minChars:1}.

Constructor Detail

AutoCompleteTextField

public AutoCompleteTextField(String name)
Construct the AutoCompleteTextField with the given name. The default text field size is 20 characters.

Parameters:
name - the name of the field

AutoCompleteTextField

public AutoCompleteTextField(String name,
                             boolean required)
Construct the AutoCompleteTextField with the given name and required status. The default text field size is 20 characters.

Parameters:
name - the name of the field
required - the field required status

AutoCompleteTextField

public AutoCompleteTextField(String name,
                             String label)
Construct the AutoCompleteTextField with the given name and label. The default text field size is 20 characters.

Parameters:
name - the name of the field
label - the label of the field

AutoCompleteTextField

public AutoCompleteTextField(String name,
                             String label,
                             boolean required)
Construct the AutoCompleteTextField with the given name, label and required status. The default text field size is 20 characters.

Parameters:
name - the name of the field
label - the label of the field
required - the field required status

AutoCompleteTextField

public AutoCompleteTextField(String name,
                             String label,
                             int size)
Construct the AutoCompleteTextField with the given name, label and size.

Parameters:
name - the name of the field
label - the label of the field
size - the size of the field

AutoCompleteTextField

public AutoCompleteTextField()
Create a AutoCompleteTextField with no name defined.

Please note the control's name must be defined before it is valid.

Method Detail

getAutoCompleteList

public abstract List getAutoCompleteList(String criteria)
Return the list of suggested values for the given search criteria.

Parameters:
criteria - the search criteria
Returns:
the list of suggested values for the given search criteria

getAutoCompleteOptions

public String getAutoCompleteOptions()
Return the JavaScript 'script.aculo.us' Autocompleter initialization options, default value is: {}.

Returns:
the JavaScript Autocompleter initialization options

setAutoCompleteOptions

public void setAutoCompleteOptions(String options)
Set the JavaScript 'script.aculo.us' Autocompleter initialization options, default value is: {minChars:1}.

Scriptaculous AutoCompleter supports sending arbitrary request parameters as part of its options. See the Ajax-AutoCompleter documentation for some examples.

Below is an example of how to send extra request parameters:

 public void onInit() {
     AutoCompleteTextField cityField = new AutoCompleteTextField("cityField");
     HtmlStringBuffer buffer = new HtmlStringBuffer();
     buffer.append("{"); // Options opens with squiggly bracket
     buffer.append(stateField.getName());
     buffer.append("=");
     buffer.append(stateField.getValue());
     buffer.append("&");
     buffer.append(idField.getName());
     buffer.append("=");
     buffer.append(idField.getValue());
     buffer.append("}"); // Options closes with squiggly bracket
     field.setAutoCompleteOptions(options.toString());
 } 
Note that you can add any of the options specified on the Ajax-AutoCompleter wiki.

Parameters:
options - the JavaScript Autocompleter initialization options

setParent

public void setParent(Object parent)
Specified by:
setParent in interface Control
Overrides:
setParent in class Field
Parameters:
parent - the parent of the Control
Throws:
IllegalStateException - if AbstractControl.name is not defined
IllegalArgumentException - if the given parent instance is referencing this object: if (parent == this)
See Also:
Field.setParent(Object)

getHeadElements

public List<Element> getHeadElements()
Return the list of HEAD elements (resources) to be included in the page. The resources are:

Specified by:
getHeadElements in interface Control
Overrides:
getHeadElements in class AbstractControl
Returns:
the list of HEAD elements to be included in the page
Throws:
IllegalStateException - if the field's name has not been set or if the field is not attached to the Page
See Also:
Control.getHeadElements()

render

public void render(HtmlStringBuffer buffer)
Render the HTML representation of the AutoCompleteTextField.

Specified by:
render in interface Control
Overrides:
render in class TextField
Parameters:
buffer - the specified buffer to render the control's output to
See Also:
AbstractControl.toString()

onInit

public void onInit()
Register the field with the parent page to intercept POST autocompletion requests.

Specified by:
onInit in interface Control
Overrides:
onInit in class AbstractControl
See Also:
Control.onInit()

onProcess

public boolean onProcess()
Process the page request and if an auto completion POST request then render an list of suggested values.

Specified by:
onProcess in interface Control
Overrides:
onProcess in class Field
Returns:
false if an auto complete request, otherwise returns true
See Also:
Control.onProcess()

renderAutoCompleteList

protected void renderAutoCompleteList(List<String> autoCompleteList)
Render the suggested auto completion list to the servlet response.

Parameters:
autoCompleteList - the suggested list of auto completion values