To use this tag: Add: <%@ taglib prefix="sx" uri="/struts-dojo-tags" %> to your page. The head tag must be included on the page, which can be configured for performance or debugging purposes. If the parseContent parameter for the head tag is false (it is false by default), then the id tag is required.

Additional Examples For more examples see Ajax and JavaScript Recipes

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)
		
		

			
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
		
		

			
required
			
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
		
		

			
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
		
		

			
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:

<sx:autocompleter name="autocompleter1" href="%{jsonList}"/>


Uses a list:

<s:autocompleter name="test"  list="{'apple','banana','grape','pear'}" autoComplete="false"/>


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

<sx:autocompleter name="mvc" href="%{jsonList}" loadOnTextChange="true" loadMinimumCount="3"/>

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:

<form id="selectForm">
     <sx:autocompleter  name="select" list="{'fruits','colors'}"  valueNotifyTopics="/changed" />
</form>  
<sx:autocompleter  href="%{jsonList}" formId="selectForm" listenTopics="/changed"/>


Set/Get selected values using JavaScript:

<sx:autocompleter  href="%{jsonList}" id="auto"/>
<script type="text/javascript">
  function getValues() {
     var autoCompleter = dojo.widget.byId("auto");
     
     //key (in the states example above, "AL")
     var key = autoCompleter.getSelectedKey();
     alert(key);
     
     //value (in the states example above, "Alabama")
     var value = autoCompleter.getSelectedValue();
     alert(value);
     
     //text currently on the textbox (anything the user typed)
     var text = autoCompleter.getText();
     alert(text);
  }

  function setValues() {
     var autoCompleter = dojo.widget.byId("auto");
     
     //key (key will be set to "AL" and value to "Alabama")
     autoCompleter.setSelectedKey("AL");
     
     //value (key will be set to "AL" and value to "Alabama")
     autoCompleter.setAllValues("AL", "Alabama");
  }
</script>


Using beforeNotifyTopics:

<script type="text/javascript">
dojo.event.topic.subscribe("/before", function(event, widget){
    alert('inside a topic event. before request');
    //event: set event.cancel = true, to cancel request
    //widget: widget that published the topic
});
</script>         

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


Using errorNotifyTopics:

<script type="text/javascript">
dojo.event.topic.subscribe("/after", function(data, request, widget){
    alert('inside a topic event. after request');
    //data : JavaScript object from parsing response
    //request: XMLHttpRequest object
    //widget: widget that published the topic
});
</script>        

<sx:autocompleter afterNotifyTopics="/after" href="%{#ajaxTest}" />


Using errorNotifyTopics:

<script type="text/javascript">
dojo.event.topic.subscribe("/error", function(error, request, widget){
    alert('inside a topic event. on error');
    //error : error object (error.message has the error message)
    //request: XMLHttpRequest object
    //widget: widget that published the topic
});
</script>

<sx:autocompleter errorNotifyTopics="/error" href="%{#ajaxTest}" />


Using valueNotifyTopics:

<script type="text/javascript">
dojo.event.topic.subscribe("/value", function(value, key, text, widget){
    alert('inside a topic event. after value changed');
    //value : selected value (like "Florida" in example above)
    //key: selected key (like "FL" in example above)
    //text: text typed into textbox
    //widget: widget that published the topic
});
</script>   

<sx:autocompleter valueNotifyTopics="/value" href="%{#ajaxTest}" />



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.