Using Spry Widgets: Auto-suggest Overview

The Auto-suggest widget is a form text field used as a search field. As the user types in the field, a list of matching hints will list underneath the text field. Users can select from the hinted list. The Auto-suggest widget is different than other Spry widgets because it is a data-widget hybrid. This means that is has the markup structure of a widget and it instantiated with a script below the markup, but it depends on a data set for the suggestion data.

Anatomy of the Auto-suggest widget

The Auto-suggest widget has a container DIV, an input field and another DIV that contains the suggest results. The suggestion results can be formatted however you wish. The widget, as always, has a constructor script that follows the widget markup. This constructor has 4 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 ac3 = new Spry.Widget.AutoSuggest("productSampleDiv", "productMenuDiv", "dsProducts3", "name", {hoverSuggestClass: 'hover', minCharsType: 0, containsString: true, maxListItems: 0});
</script>

Breaking down the markup

The outer DIV is the main container for the widget. The ID attribute is required since it is referenced by the constructor.
The widget requires one text input field for the search term.
The inner DIV is the container for the results. The id is required since the constructor needs it. This container also needs to be a spry:region so it can display the results.
The markup inside the results container can be whatever you wish, but it needs to be a spry:repeat region and the spry:suggest attribute value is the data reference for the results.

As with all widgets, the actual markup doesn't matter, as long as it follows the rules of HTML (ie. <p> tags cannot contain other block elements).

Breaking down the constructor:

The var is the name of the widget.
The Spry.Widget.AutoSuggest object has 4 required attributes. They must be in this order:
- ID of the main widget container. ("productSampleDiv")
- ID of the results container.
- The data set that contains the search column.
- The name(s) of the search column(s).

There are a series of optional attributes for the constructor:

Option	Definition	Default	Values
containsString	By default, the widget returns results that "starts" with the typed string. Setting containString to 'true' will return results where the typed string is anywhere within the result.	false	true false
minCharsType	This determines how many characters have to be typed before results are listed. This is helpful in improving performance, esp. if retrieving results directly from the server		number
maxListItems	Determines the maximum number of items in the list		number
hoverSuggestClass	This attribute takes a CSS class that will be applied while hovering over the results list.		CSS class name
loadFromServer	This attribute will fetch results from the server directly, rather than from the cached data set. This will trump the default data set caching setting and always fetch the results from the server.	false	true false
urlParam	This is the URL parameter name to which the search field value is attached. i.e. www.adobe.com?urlParam=searchValue	required if loadFromServer is true.

Note that the auto suggest works by filtering the data set. Initially, the data set filters out everything. As you type, the filter is loosened to allow in the expected results. This means that if you have other Spry regions hooked to the same data set as the auto suggest widget, those regions will not show content when the page loads. You may want to dedicate a data set specifically for the auto suggest.

Building an Auto suggest widget

In your page, attach the Auto Suggest javascript file. Because this widget uses Spry data, we attach the required Spry data files: SpryData.js and xpath.js. We also use CSS to show and hide results. Attach the SpryAutoSuggest.css as well.

<head>
<script language="JavaScript" type="text/javascript" src="includes/xpath.js"></script>
<script language="JavaScript" type="text/javascript" src="includes/SpryData.js"></script>
<script language="JavaScript" type="text/javascript" src="includes/SpryAutoSuggest.js"></script>
<link href="includes/SpryAutoSuggest.css" rel="stylesheet" type="text/css" />
<link
</head>

To the document body, add a container <DIV> and give it a unique ID.
```
<div id="mySuggest"></div>
```
Add the input field to the DIV. This will be the search field.
```
<div id="mySuggest">
<input type="text" />
</div>
```

Add the results container <DIV>. GIve it an ID.

<div id="mySuggest">
<input type="text" />
  <div id="resultsDIV">
  </div>
</div>

Since this is a data hybrid widget, we need a data set from which we will get the results. Create a data set in the document head.

<head>
<script language="JavaScript" type="text/javascript" src="includes/xpath.js"></script>
<script language="JavaScript" type="text/javascript" src="includes/SpryData.js"></script>
<script language="JavaScript" type="text/javascript" src="includes/SpryAutoSuggest.js"></script>
<script language="JavaScript" type="text/javascript">
  var ds1 = new Spry.Data.XMLDataSet("data/products.xml","products/product");
</script>
</head>

Now reference this data set in the results container by making it a spry:region.

<div id="mySuggest">
<input type="text" />
  <div id="resultsDIV" spry:region="ds1">
  </div>
</div>

Add the markup you want for the results. This can be whatever you wish, but it will be a spry:repeat region to look through the results. Also, to this markup, add the data reference that will be the results column.
```
<div id="mySuggest">
<input type="text" />
  <div id="resultsDIV" spry:region="ds1">
    <ul>
      <li spry:repeat="ds1">{name}</li>
    </ul>
  </div>
</div>
```
Add spry:suggest attribute to the element that will be highlighed. The value of this attribute will be filled in the text field when the row of the repeat region will be selected.
```
<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>
```

Now that the markup is complete, we will add the constructor script. BELOW the markup, add a script tag and write the constructor within. The values are case sensitive.

<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 theSuggest = new Spry.Widget.AutoSuggest("mySuggest","resultsDIV", "ds1","name");
</script>

The values are ("theContainerID","theResultsContainerID","theDataSetName","theResultsDataColumn")

That's it. Preview the page and typing in the field should show results displayed below the field.

Adding Options

If you want to add some optional functionality, add the values to the constructor. The options added below will force the suggest to start after the 3rd character is typed and will also change the search parameter from "starts with" to "contains". Options are contained within {}.

<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 theSuggest = new Spry.Widget.AutoSuggest("mySuggest","resultsDIV", "ds1","name",{containsString:true,minCharsType:3});
</script>

Or with more options:

<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 theSuggest = new Spry.Widget.AutoSuggest("mySuggest","resultsDIV", "ds1", "name",{containsString:true, minCharsType:3,maxListItems:10, containsString:true, hoverSuggestClass:mySuggest});
</script>