AutoCompleteEntry

Overview

Since 3.1

ace:autoCompleteEntry is a text input component that displays a list of suggested possible values, for the current input, as the user types. It provides different built-in filtering modes to generate a list of suggestions, and it also supports custom filtering modes for more specific and/or complex filtering requirements. It works by binding a list of standard SelectItem objects to the component, and it is also possible to bind a list of arbitrary data objects. The component also supports various options to control its behaviour in detail.

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

In its simplest form, ace:autoCompleteEntry is set up by nesting a list of SelectItem's inside the component's tag, as in the following code snippet.

            <ace:autoCompleteEntry id="autoComplete"
                                   value="#{autoCompleteEntryBean.selectedText}">
                <f:selectItems value="#{autoCompleteEntryBean.items}"/>
            </ace:autoCompleteEntry>

The 'label' property of the SelectItem objects will be used to match the possible results with the input that the user has typed so far. In the case above, the default matching mode will be applied, which is 'startsWith'.

A more complex example is shown below and involves using arbitrary data objects (POJOs) and the ability to nest arbitrary components in each row. In this case, it is necessary to specify the list of data objects in the listValue attribute of the component. It is also necessary to give a name for the variable that will be used to represent each object in the markup in the listVar attribute, and one must also tell the component according to which property the filtering should be done in the filterBy attribute. Then, a facet named 'row' is used to nest any arbitrary components and markup, using the variable to reference different properties of the data object.

            <ace:autoCompleteEntry id="autoCompleteFacet"
                                   value="#{autoCompleteEntryFacetBean.selectedText}"
                                   listVar="city"
                                   listValue="#{autoCompleteEntryFacetBean.cities}"
                                   filterBy="#{city.name}">
                 <f:facet name="row">
                    <h:panelGrid columns="3">
                        <h:graphicImage library="css/images" name="house.png"/>
                        <h:outputText value="#{city.name}" />
                        <h:outputText value="#{city.country}" />
                    </h:panelGrid>
                 </f:facet>
            </ace:autoCompleteEntry>

ace:autoCompleteEntry vs. ace:comboBox. The ace:autoCompleteEntry and the ace:comboBox components have similar functionality. However, they are better suited for different use cases. Use the ace:autoCompleteEntry component for large data sets and when the input can be completely arbitrary (e.g. a search engine). Because the results are filtered in the server side, it is possible to access far more results and filter them much faster than if they were in the client side. It is also recommended when doing more complex, custom filtering that cannot be done with the basic matching modes. The autocomplete capabilities of the ace:comboBox component are only client-side, so it is recommended for smaller data sets (<1000 possible values). It is also recommended for cases where the expected value 80% of the time is part of a set small set of options (<10), but you don't want to restrict the user from entering any other arbitrary input.

Attributes

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available here.

The filterMatchMode attribute specifies how the different options will be evaluated to match the current input. The possible values are "contains", "exact", "startsWith", "endsWith" and "none". The default value is "startsWith". If "none" is used, the component will take the list of items as it is and display the first number of rows specified by the rows attribute. This is useful in situations where the application needs to dynamically generate the list of items after some more custom or complex filtering.

The listValue attribute is used to bind a list of items that the component will use to present as options when rendering via a facet. They can be either SelectItems or POJOs.

The listVar attribute is used to refer to an individual item when rendering via a facet.

The filterBy attribute is a ValueExpresssion that specifies the property of the item (using listVar) according to which the filtering should be done, when rendering via a facet.

The caseSensitive attribute specifies whether the filtering done by the component should be case sensitive or not.

The direction attribute forces the list of options to appear either "up" or "down". The default is "auto", where the component finds if there's enough space to display the list below the text field, otherwise it tries to display it above it.

Client Behavior Events

submit	Fired any time the value of the text input field is submitted to the server, either by typing a symbol, clicking on an option or pressing enter.
blur	Fired any time the text input field loses focus.
textChange	Fired any time the user adds or removes characters from the text field by typing or by pasting text.
valueChange	(default event) Fired when the user gives a more definite input for this component either by clicking on an option from the list, or selecting an option with the keyboard, or pressing enter on the text field.

JavaScript APIs

ICEfaces 3.x

The client side component object is exposed through the global variable name specified in the widgetVar attribute.

ICEfaces 4+

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

var widget = ice.ace.instance('frm:componentId);

The ice.ace.instance function requires the full client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use prependId="false" in the enclosing form (e.g. <h:form prependId="false">).

This component doesn't have a client-side API made specifically to be used by application developers. However, the component's internal methods and variables can be accessed in this way, including the underlying jQuery object and objects from underlying Javascript libraries (if applicable), and can be used for whatever purpose a developer might have in mind.

Keyboard and ARIA Support

The following ARIA roles are supported: textbox.

Facet Rendering

It is possible to customize the way in which the option items are displayed by means of the 'row' facet. You can add any arbitrary content, as in the following example.

<ace:autoCompleteEntry id="autoCompleteFacet"
					   value="#{autoCompleteEntryFacetBean.selectedText}"
					   rows="10" width="300"
					   filterMatchMode="startsWith"
					   listVar="city"
					   listValue="#{autoCompleteEntryFacetBean.cities}"
					   filterBy="#{city.name}"
					   label="Cities of the World:"
					   labelPosition="left">
	 <f:facet name="row">
		<h:panelGrid columns="3" width="100%" columnClasses="col10,col50,col25">
			<h:graphicImage value="resources/css/images/house.png" alt="House"/>
			<h:outputText value="#{city.name}" />
			<h:outputText value="#{city.country}" />
		</h:panelGrid>
	 </f:facet>
</ace:autoCompleteEntry>

Labels

This component supports built-in labels. The text specified in the label attribute will be rendered next to the main input field of this component. The position specified by labelPosition will determine where this label is going to be rendered; the possible values are left, right, top, bottom, none and inField (to render the label in the field itself).

Required Indicator

The requiredIndicator attribute specifies the text to be displayed next to the main input field when this component is marked as required. When, this component is not marked as required, then the text specified in the optionalIndicator is going to be rendered. The indicatorPosition attribute determines where this indicator text is going to the rendered; the possible values are left, right, top, bottom, labelLeft, labelRight, and none.

Required Styling

Then this component is marked as required, the main input field receives the CSS class ui-state-required, otherwise, it receives the CSS class ui-state-optional. When this component is marked as invalid by the app, it will be rendered with the CSS class ui-state-error. These CSS classes can be used to add custom styling to this component, in order indicate its current state in a more visual way.

CSS Classes

The following markup represents the basic HTML structure of the component and the CSS classes it uses.

<!-- Root container -->
<div class="[user defined classes]">
	<span>
		<!-- Text field -->
		<input class="ui-inputfield ui-widget ui-state-default ui-corner-all ui-state-optional" style="[user defined styles]"  />
		<!-- List of options -->
		<span>
			<div class="ui-widget ui-widget-content ui-corner-all">
				<div>
					<!-- Individual option -->
					<div class="ui-widget-content">Option</div>
				</div>
			</div>
		</span>
	</span>
</div>

Additionally, the informal class name can be added when using the component in facet mode to components and elements that are rendered for display purposes but that are not part of the value that is submitted to the server.

Known Issues

None.

Other Notes

The autocomplete functionality can be done entirely in the client side if the clientSide attribute is set to true. Client-side mode can be faster, as no round trips to the server need to be made. However, if the list of possible results is too large, the browser might become slower, since the entire list has to be stored in the client as HTML nodes. It is recommended not to use lists of more than 1000 items when using the client-side mode.