autocompleter

NOTE: Ajax template (Dojo plugin) is deprecated and won’t be supported any longer.

Description

The autocomplete tag is a combobox that can autocomplete text entered on the input box. If an action is used to populate the autocompleter, the output of the action must be a well formed JSON string.

The autocompleter follows this rule to find its datasource:

1. If the response is an array, assume that it contains 2-dimension array elements, like:

 [
      ["Alabama", "AL"],
      ["Alaska", "AK"]
 ]
 

2. If a value is specified in the "dataFieldName" attribute, and the response has a field with that name, assume that's the datasource, which can be an array of 2-dimension array elements, or a map, like (assuming dataFieldName="state"):

 {
      "state" : [
           ["Alabama","AL"],
           ["Alaska","AK"]
      ]
 }     
 or
 {
      "state" : {
            "Alabama" : "AL",
            "Alaska" : "AK"
      }
 }
 

3. If there is a field that starts with the value specified on the "name" attribute, assume that's the datasource, like (assuming name="state"):

 {
      "states" : [
           ["Alabama","AL"],
           ["Alaska","AK"]
      ]
 }
 

4. Use first array that is found, like:

 {
      "anything" : [
            ["Alabama", "AL"],
            ["Alaska", "AK"]
     ]       
 }
 
5. If the response is a map, use it (recommended as it is the easiest one to generate):
 
 {
      "Alabama" : "AL",
      "Alaska" : "AK"
 }
 



__Parameters__




		


			


				
Dynamic Attributes Allowed:
 false

			

			


				
 

			

			


				
Name

				
Required

				
Default

				
Evaluated

				
Type

				
Description

			

				


					
accesskey

					
false

					


					
false

					
String

					
Set the html accesskey attribute on rendered html element

				

				


					
afterNotifyTopics

					
false

					


					
false

					
String

					
Comma delimmited list of topics that will published after the request(if the request succeeds)

				

				


					
autoComplete

					
false

					
false

					
false

					
Boolean

					
Whether autocompleter should make suggestion on the textbox

				

				


					
beforeNotifyTopics

					
false

					


					
false

					
String

					
Comma delimmited list of topics that will published before the request

				

				


					
cssClass

					
false

					


					
false

					
String

					
The css class to use for element

				

				


					
cssErrorClass

					
false

					


					
false

					
String

					
The css error class to use for element

				

				


					
cssErrorStyle

					
false

					


					
false

					
String

					
The css error style definitions for element to use

				

				


					
cssStyle

					
false

					


					
false

					
String

					
The css style to use for element

				

				


					
dataFieldName

					
false

					
Value specified in 'name'

					
false

					
String

					
Name of the field in the returned JSON object that contains the data array

				

				


					
delay

					
false

					
100

					
false

					
Integer

					
Delay before making the search

				

				


					
disabled

					
false

					
false

					
false

					
Boolean

					
Enable or disable autocompleter

				

				


					
dropdownHeight

					
false

					
120

					
false

					
Integer

					
Dropdown's height in pixels

				

				


					
dropdownWidth

					
false

					
same as textbox

					
false

					
Integer

					
Dropdown's width

				

				


					
emptyOption

					
false

					


					
false

					
String

					
Decide if an empty option is to be inserted. Default false.

				

				


					
errorNotifyTopics

					
false

					


					
false

					
String

					
Comma delimmited list of topics that will published after the request(if the request fails)

				

				


					
errorPosition

					
false

					


					
false

					
String

					
Define error position of form element (top|bottom)

				

				


					
forceValidOption

					
false

					
false

					
false

					
Boolean

					
Force selection to be one of the options

				

				


					
formFilter

					
false

					


					
false

					
String

					
Function name used to filter the fields of the form

				

				


					
formId

					
false

					


					
false

					
String

					
Form id whose fields will be serialized and passed as parameters

				

				


					
headerKey

					
false

					


					
false

					
String

					
Set the header key for the header option.

				

				


					
headerValue

					
false

					


					
false

					
String

					
Set the header value for the header option.

				

				


					
href

					
false

					


					
false

					
String

					
The URL used to load the options

				

				


					
iconPath

					
false

					


					
false

					
String

					
Path to icon used for the dropdown

				

				


					
id

					
false

					


					
false

					
String

					
The id to use for the element

				

				


					
indicator

					
false

					


					
false

					
String

					
Id of element that will be shown while request is made

				

				


					
javascriptTooltip

					
false

					
false

					
false

					
Boolean

					
Use JavaScript to generate tooltips

				

				


					
key

					
false

					


					
false

					
String

					
Set the key (name, value, label) for this particular component

				

				


					
keyName

					
false

					


					
false

					
String

					
Name of the field to which the selected key will be assigned

				

				


					
keyValue

					
false

					


					
false

					
String

					
Initial key value

				

				


					
label

					
false

					


					
false

					
String

					
Label expression used for rendering an element specific label

				

				


					
labelSeparator

					
false

					
:

					
false

					
String

					
String that will be appended to the label

				

				


					
labelposition

					
false

					


					
false

					
String

					
Define label position of form element (top/left)

				

				


					
list

					
false

					


					
false

					
String

					
Iteratable source to populate from.

				

				


					
listKey

					
false

					


					
false

					
String

					
Set the key used to retrive the option key.

				

				


					
listValue

					
false

					


					
false

					
String

					
Set the value used to retrive the option value.

				

				


					
listenTopics

					
false

					


					
false

					
String

					
Topic that will trigger a reload

				

				


					
loadMinimumCount

					
false

					
3

					
false

					
Integer

					
Minimum number of characters that will force the content to be loaded

				

				


					
loadOnTextChange

					
false

					
true

					
false

					
Boolean

					
Options will be reloaded everytime a character is typed on the textbox

				

				


					
maxLength

					
false

					


					
false

					
Integer

					
Deprecated. Use maxlength instead.

				

				


					
maxlength

					
false

					


					
false

					
Integer

					
HTML maxlength attribute

				

				


					
name

					
false

					


					
false

					
String

					
The name to set for element

				

				


					
notifyTopics

					
false

					


					
false

					
String

					
Topics that will be published when content is reloaded

				

				


					
onblur

					
false

					


					
false

					
String

					
 Set the html onblur attribute on rendered html element

				

				


					
onchange

					
false

					


					
false

					
String

					
Set the html onchange attribute on rendered html element

				

				


					
onclick

					
false

					


					
false

					
String

					
Set the html onclick attribute on rendered html element

				

				


					
ondblclick

					
false

					


					
false

					
String

					
Set the html ondblclick attribute on rendered html element

				

				


					
onfocus

					
false

					


					
false

					
String

					
Set the html onfocus attribute on rendered html element

				

				


					
onkeydown

					
false

					


					
false

					
String

					
Set the html onkeydown attribute on rendered html element

				

				


					
onkeypress

					
false

					


					
false

					
String

					
Set the html onkeypress attribute on rendered html element

				

				


					
onkeyup

					
false

					


					
false

					
String

					
Set the html onkeyup attribute on rendered html element

				

				


					
onmousedown

					
false

					


					
false

					
String

					
Set the html onmousedown attribute on rendered html element

				

				


					
onmousemove

					
false

					


					
false

					
String

					
Set the html onmousemove attribute on rendered html element

				

				


					
onmouseout

					
false

					


					
false

					
String

					
Set the html onmouseout attribute on rendered html element

				

				


					
onmouseover

					
false

					


					
false

					
String

					
Set the html onmouseover attribute on rendered html element

				

				


					
onmouseup

					
false

					


					
false

					
String

					
Set the html onmouseup attribute on rendered html element

				

				


					
onselect

					
false

					


					
false

					
String

					
Set the html onselect attribute on rendered html element

				

				


					
preload

					
false

					
true

					
false

					
Boolean

					
Load options when page is loaded

				

				


					
readonly

					
false

					
false

					
false

					
Boolean

					
Whether the input is readonly

				

				


					
requiredLabel

					
false

					
false

					
false

					
Boolean

					
If set to true, the rendered element will indicate that input is required

				

				


					
requiredPosition

					
false

					


					
false

					
String

					
Define required position of required form element (left|right)

				

				


					
resultsLimit

					
false

					
30

					
false

					
Integer

					
Limit how many results are shown as autocompletion options, set to -1 for unlimited results

				

				


					
searchType

					
false

					
stringstart

					
false

					
String

					
how the search must be performed, options are: 'startstring', 'startword' and 'substring'

				

				


					
showDownArrow

					
false

					
true

					
false

					
Boolean

					
Show or hide the down arrow button

				

				


					
size

					
false

					


					
false

					
Integer

					
HTML size attribute

				

				


					
style

					
false

					


					
false

					
String

					
The css style definitions for element to use - it's an alias of cssStyle attribute.

				

				


					
tabindex

					
false

					


					
false

					
String

					
Set the html tabindex attribute on rendered html element

				

				


					
template

					
false

					


					
false

					
String

					
The template (other than default) to use for rendering the element

				

				


					
templateCssPath

					
false

					


					
false

					
String

					
Template css path

				

				


					
templateDir

					
false

					


					
false

					
String

					
The template directory.

				

				


					
title

					
false

					


					
false

					
String

					
Set the html title attribute on rendered html element

				

				


					
tooltip

					
false

					


					
false

					
String

					
Set the tooltip of this particular component

				

				


					
tooltipConfig

					
false

					


					
false

					
String

					
Deprecated. Use individual tooltip configuration attributes instead.

				

				


					
tooltipCssClass

					
false

					
StrutsTTClassic

					
false

					
String

					
CSS class applied to JavaScrip tooltips

				

				


					
tooltipDelay

					
false

					
Classic

					
false

					
String

					
Delay in milliseconds, before showing JavaScript tooltips 

				

				


					
tooltipIconPath

					
false

					


					
false

					
String

					
Icon path used for image that will have the tooltip

				

				


					
transport

					
false

					
XMLHTTPTransport

					
false

					
String

					
Transport used by Dojo to make the request

				

				


					
type

					
false

					
text

					
false

					
String

					
Specifies the html5 type element to display. e.g. text, email, url

				

				


					
value

					
false

					


					
false

					
String

					
Preset the value of input element

				

				


					
valueNotifyTopics

					
false

					


					
false

					
String

					
Comma delimmited list of topics that will published when a value is selected

				

		




__Examples__

Get list from an action:




```xml
 

```



Uses a list:




```xml
 

```



Autocompleter that reloads its content everytime the text changes (and the length of the text is greater than 3):




```xml
 
 
 The text entered on the autocompleter is passed as a parameter to the url specified in "href", like (text is "struts"):
  
 http://host/example/myaction.do?mvc=struts

```



Linking two autocompleters:




```xml
 

      
   
 

```



Set/Get selected values using JavaScript:




```xml
 
 

```



Using beforeNotifyTopics:




```xml
          
 
 <sx:autocompleter beforeNotifyTopics="/before" href="%{#ajaxTest} />

```



Using errorNotifyTopics:




```xml
         
 
 

```



Using errorNotifyTopics:



 
 
 



Using valueNotifyTopics:



    
 
 



__Caveats__

+ The service that is producing the HTTP Response with JSON response to the Autocompleter tag must set the HTTP Header Response Content-Type to `text/json`. JSON has its own MIME type, which this tag expects.

+ Since 2.0.9, there is a change in the value:key order. Now, the value **must** come before the key.