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.

About Spry Widgets

A Spry widget is a page element containing built-in behaviors and functions that provide a richer user experience by enabling user interaction. These behaviors can include functionality that lets users show or hide content on the page, change the appearance (such as color of the input) in the page, interact with menu items, and much more.

The Spry framework supports a set of re-usable widgets, written in standard HTML, CSS, and JavaScript. You can easily insert these widgets — the code is HTML and JavaScript at its simplest — and then style the widget according to your liking.

Each widget in the Spry framework is associated with unique CSS and JavaScript files. The CSS file contains everything necessary for styling the widget, and the JavaScript file gives the widget its functionality. You must link both of these files to the page on which you want the widget to function and appear styled. Otherwise, the widget won’t have any functionality or styling. For more information, see the appropriate sections about linking associated files in the topics that follow.

The CSS and JavaScript files associated with a given widget are named after the widget, so it’s easy for you to know which files correspond to which widgets. (For example, the files associated with the Auto Suggest widget are called SpryAutoSuggest.css and SpryAutoSuggest.js).

Anatomy of the Auto Suggest widget
Building an Auto Suggest widget
Auto Suggest widget options
Keyboard Navigation

See the Auto Suggest reference file and sample.

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" name="product"/> 
   <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 HTML tag 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.
moveNextKeyCode	This option allows the user to assign a specific key to go to the next suggestion when the list of suggestions appears. Keyboard code numbers are described here. The value of the option is the keyboard code number.	number	40 (Down Arrow key code)
movePrevKeyCode	This option allows the user to assign a specific key to go to the previous suggestion when the list of suggestions appears. Keyboard code numbers are described here. The value of the option is the keyboard code number.	number	38 (Up Arrow key code)

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" />
</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" name="product" />
</div>

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

<div id="mySuggest">
	<input type="text" name="product"/>
	<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>
<link href="includes/SpryAutoSuggest.css" rel="stylesheet" type="text/css" />
<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" name="product"/>
  <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" name="product"/>
  <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" name="product"/>
  <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" name="product"/>
  <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.

Note: This chapter details only how to build the Spry Auto Suggest widget with XML Data Set. The steps to use a different Data Sets like JSON or HTML are the same, the things that should be changed are the JS files to be included in your page and the specific Data Set JS creation code.

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" name="product"/>
  <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" name="product"/>
  <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>

Keyboard navigation

Making widgets accessible for keyboard navigation is an important part of every widget. Keyboard navigation lets the user control the widget with arrow keys and custom keys.

You can set custom keys for keyboard navigation. Custom keys are set as arguments of the autosuggest constructor script:

<script type="text/javascript">
	var theSuggest = new Spry.Widget.AutoSuggest("mySuggest","resultsDIV", "ds1","name",{movePrevKeyCode: 33 /* PgUp key */, moveNextKeyCode: 34 /* PgDn key */});
</script>