Auto-suggest widget overview and structure

The Auto-suggest widget is a form text field that’s used as a search field. As the user types in the field, a list of matching hints appears beneath the text field. Users can then select options from the items in the hinted list. The Auto-suggest widget is different than other Spry widgets because it is a data-widget hybrid. This means that it has the code structure of a widget, including an instantiation script below the widget code, but it depends on a data set for the suggestion data.

Note: You should be familiar with both Spry widgets and Spry data sets before you work with the Auto-suggest widget. If you’re not familiar with them, see any of the widget overviews before proceeding, as well as Working with Spry data sets. This overview does not present basic widget and data set concepts.

In the following example, the Auto-suggest widget has a container div, an input field, and another inner div that displays the suggestion results. You can format the suggestion results in any way. The widget has a constructor script that follows the widget code. This constructor has four required values and a set of optional values.

<div id="productSampleDiv" class="container">
   <input type="text" id="productFilterDiv" /> 
   <div id="productMenuDiv" spry:region="dsProducts3">
   <span spry:repeat="dsProducts3" spry:suggest="{name}">{name}<br/></span>
   </div>
</div>
<script type="text/javascript">
   var as1 = new Spry.Widget.AutoSuggest("productSampleDiv", "productMenuDiv", "dsProducts3", "name", {hoverSuggestClass: 'hover', minCharsType: 0, containsString: true, maxListItems: 0});
</script>

The following is a breakdown of the widget code:

The outer div (with the id of productSampleDiv) is the main container for the widget. The id attribute is required because you need to reference it in the constructor.
The widget requires one text input field for the search term.
The inner div (with the id of productMenuDiv) is the container that displays the results. Again, the id attribute is required because you need to reference it in the constructor. You must also make this container a spry:region so that Spry can display the results.
The code inside the results container can be whatever you want, but the tag needs to have two attributes: spry:repeat and spry:suggest. The spry:repeat attribute is responsible for repeating the suggestion data from the data set in a list, and the spry:suggest attribute is responsible for populating the text field with whatever values the user selects from the list. The value of the spry:suggest attribute is the data reference (column name) that you want to use to display results.

As with all widgets, the actual tags you use don’t matter, as long as they follow standard HTML rules (for example, p tags cannot contain other block elements).

The Spry.Widget.AutoSuggest constructor has four required attributes. You must enter them in the following order:

ID of the main widget container
ID of the results container
The data set that contains the search column
The names of the search columns

The Auto-suggest widget works by filtering the data set you specify. Initially, the data set filters out all of the data. As you type, the filter relaxes to allow the expected results to display. This means that if you have other Spry regions connected to the same data set that the Auto-suggest widget uses, those regions do not display content when the page loads in the browser. Additionally, when the widget filters data, all regions depending on the same data set will be affected. For this reason, you should dedicate a data set specifically for the Auto-suggest widget.

The following table provides additional options that you can use in the widget constructor.

Option	Description	Values	Default value
containsString	By default, the widget returns results that start with the typed string. Setting `containString` to `true` returns results where the typed string appears anywhere within the result, not just at the beginning.	true or false	false
minCharsType	Determines how many characters the user must type before the widget displays results. This option is useful for improving performance, especially if you are retrieving results directly from the server.	number
maxListItems	Determines the maximum number of items in the results list.	number
hoverSuggestClass	Takes a CSS class that Spry applies to the results list while hovering over the list.	CSS class name
loadFromServer	Retrieves results from the server directly, rather than from the cached data set. This option always overrides the default data set caching setting and retrieves the results directly from the server.	true or false	false
urlParam	The URL parameter name to which the search field value is attached. For example, `www.adobe.com?urlParam=searchValue.`		Required if loadFromServer is true.

Constructor option examples

The options in the following example force the auto-suggestion to start after the third character is typed in the text field. The containsString:true option causes the widget to make suggestions when the user types a character that exists anywhere in the suggestion result, and not just at the beginning.

and also changes the search parameter from "starts with" to "contains". Options are enclosed within braces ({}).

<div id="mySuggest">
	<input type="text" />
  	<div id="resultsDIV" spry:region="ds1">
    <ul>
      <li spry:repeat="ds1" spry:suggest="{name}">{name}</li>
    </ul>
  </div>
</div>
<script type="text/javascript">
var as1 = new Spry.Widget.AutoSuggest("mySuggest","resultsDIV", "ds1","name",{containsString:true,minCharsType:3});
</script>

Here’s an example with more options set:

<script type="text/javascript">
var theSuggest = new Spry.Widget.AutoSuggest("mySuggest","resultsDIV", "ds1", "name",{containsString:true, minCharsType:3,maxListItems:10, hoverSuggestClass:mySuggest});
</script>

Spry

Auto-suggest widget overview and structure

Constructor option examples

document.write(terms_Related_Information);