Edit on GitHub

# 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"
          }
     }

</pre>

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.