org.apache.click.extras.control
Class AutoCompleteTextField

java.lang.Object
  org.apache.click.control.AbstractControl
      org.apache.click.control.Field
          org.apache.click.control.TextField
              org.apache.click.extras.control.AutoCompleteTextField

All Implemented Interfaces:

Serializable, Control, Stateful

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):

• click/extras-control.css
• click/control.js
• click/prototype/prototype.js
• click/prototype/effects.js
• click/prototype/controls.js

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.
protected Behavior	behavior The Field Ajax Behavior provides autocomplete support.
protected Map<String,Object>	parameters Additional parameters to send to server.

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, behaviors, 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

void	addBehavior(Behavior behavior) This method is not supported and throws an UnsupportedOperationException if invoked.
protected Behavior	createBehavior() Create the field Ajax behavior instance.
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 "minChars:1".
protected Behavior	getBehavior() Return the field internal Ajax behavior instance.
List<Element>	getHeadElements() Return the list of HEAD elements (resources) to be included in the page.
Map<String,Object>	getParameters() Return this field map of additional parameters.
boolean	hasParameters() Return true if this field has additional parameters, false otherwise.
void	onInit() Register the field with the parent page to intercept POST autocompletion requests.
void	removeBehavior(Behavior behavior) This method is not supported and throws an UnsupportedOperationException if invoked.
void	render(HtmlStringBuffer buffer) Render the HTML representation of the AutoCompleteTextField.
protected void	renderAutoCompleteList(HtmlStringBuffer buffer, List<?> 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	setParameter(String name, Object value) Set the field parameter with the given parameter name and value.

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, getState, getTabIndex, getTextAlign, getTitle, getValidate, getValue, getValueObject, getWidth, isDisabled, isHidden, isReadonly, isRequired, isTrim, isValid, onProcess, removeState, renderTagBegin, restoreState, saveState, setDisabled, setError, setErrorMessage, setErrorMessage, setFocus, setForm, setHelp, setLabel, setLabelStyle, setLabelStyleClass, setListener, setParent, setParentStyleClassHint, setParentStyleHint, setReadonly, setRequired, setState, setTabIndex, setTextAlign, setTitle, setTrim, setValidate, setValue, setValueObject, setWidth

Methods inherited from class org.apache.click.control.AbstractControl

addStyleClass, appendAttributes, dispatchActionEvent, getActionListener, getAttribute, getAttributes, getBehaviors, getContext, getHtmlImports, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasBehaviors, hasStyles, isAjaxTarget, onDeploy, onDestroy, onRender, removeStyleClass, 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.

parameters

protected Map<String,Object> parameters

Additional parameters to send to server. Note the AutoCompleteTextField id is always sent as a parameter to the server in order for Click to identify the field.

behavior

protected Behavior behavior

The Field Ajax Behavior provides autocomplete support.

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 "minChars:1".

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.

For the full list of available options, see the Ajax-AutoCompleter documentation.

Below is an example of how to set some of these options:

 public void onInit() {
     AutoCompleteTextField cityField = new AutoCompleteTextField("cityField");
     field.setAutoCompleteOptions("minChars:1, frequency: 0.6");
 } 

Please note: to send additional request parameters use setParameter(java.lang.String, java.lang.Object) instead

Parameters:

options - the JavaScript Autocompleter initialization options

hasParameters

public boolean hasParameters()

Return true if this field has additional parameters, false otherwise.

Returns:

true if this field has additional parameters, false otherwise

getParameters

public Map<String,Object> getParameters()

Return this field map of additional parameters.

Returns:

this field map of additional parameters

setParameter

public void setParameter(String name,
                         Object value)

Set the field parameter with the given parameter name and value. If the value is null the parameter will be removed.

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 additional request parameters:

 public void onInit() {
     AutoCompleteTextField cityField = new AutoCompleteTextField("cityField");
     cityField.setParameter(stateField.getName(), stateField.getValue());
 } 

Parameters:

name - the attribute name

value - the attribute value

getHeadElements

public List<Element> getHeadElements()

Return the list of HEAD elements (resources) to be included in the page. The resources are:

• /click/extras-control.css
• /click/control.js
• /click/prototype/prototype.js
• /click/prototype/effects.js
• /click/prototype/controls.js

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()

addBehavior

public void addBehavior(Behavior behavior)

This method is not supported and throws an UnsupportedOperationException if invoked.

Overrides:

addBehavior in class AbstractControl

Parameters:

behavior - the behavior to add

Throws:

UnsupportedOperationException - this field uses an internal behavior instead

removeBehavior

public void removeBehavior(Behavior behavior)

This method is not supported and throws an UnsupportedOperationException if invoked.

Overrides:

removeBehavior in class AbstractControl

Parameters:

behavior - the behavior to add

Throws:

UnsupportedOperationException - if invoked

getBehavior

protected Behavior getBehavior()

Return the field internal Ajax behavior instance.

Returns:

the field internal Ajax behavior instance

createBehavior

protected Behavior createBehavior()

Create the field Ajax behavior instance.

Returns:

the field Ajax behavior instance

renderAutoCompleteList

protected void renderAutoCompleteList(HtmlStringBuffer buffer,
                                      List<?> autoCompleteList)

Render the suggested auto completion list to the servlet response.

Parameters:

autoCompleteList - the suggested list of auto completion values