AJAX Suggestions - Implementation

General implementation

What you need to do is to first include the JavaScript file; ajaxSuggestions.js for a stand-alone version, or ajaxSuggestions-DOMAssistant.js together with the other DOMAssistant modules (Note: remember to call the init() method of the ajaxSuggestions object, with the approach you find suitable, when using the DOMAssistant version).

Then, just add two CSS classes to the input elements you want to add the AJAX Suggestions functionality to, ajax-suggestion and url-the-actual-URL, where you should replace the-actual-URL with your desired URL. The HTML code will look something like this:

<input type="text" class="ajax-suggestion url-ajax-demo.php">

It is also recommended to have the HTML code for the elements that will present the suggestions in your original HTML code. For example:


<div id="search-result-suggestions">
	<h4>Top 5 results</h4>
	<div id="search-results"></div>
</div>

Please note that AJAX Suggestions supports multiple elements in the same web page, who can also use different URLs for their AJAX calls. The same element is used for presenting the results, so it will only show you the results/suggestions for the latest search.

An example reply

An example reply can look any way you want; only your imagination will hold you back! Below is just a simple code example of a list with suggestions:


<ul>
	<li><a href="1" class="item">Suggestion #1</a></li>
	<li><a href="2" class="item">Suggestion #2</a></li>
	<li><a href="3" class="item">Suggestion #3</a></li>
	<li><a href="4" class="item">Suggestion #4</a></li>
	<li><a href="5" class="item">Suggestion #5</a></li>
</ul>
<p><a href="/" class="item"><b>Search for all items</b></a></p>

Settings

AJAX Suggestions gives you a number of settings for you to get the most out of your usage. The different settings, available at the top of the ajaxSuggestions JavaScript file, are described below. Here are the default settings:

Default settings


elmIdToPresentResultsIn : "search-results",
elmIdResultsContainer : "search-result-suggestions",
charactersBeforeSearch : 2,
timeBeforeSuggest : 200, // In milliseconds
sameWidthAsInputElm : false,
offsetLeft: 0,
offsetTop : 0,
urlExt : "search=",
addSearchTermToQueryString : true,
addKeyNavigationEvents : true,
hideResultsOnDocumentClick : true,
itemClassName : "item",
itemSelectedClassName : "selected",
itemInsertValueIntoInputClassName : "choose-value",
itemInsertValueSetFocusToInput : true,
hideResultsWhenInsertValueIsSelected : true,
itemSeparator : ";",
turnAutoCompleteOff : true,

Customizable settings

 

elmIdToPresentResultsIn
The id of the element to present the results/suggestions in.
elmIdResultsContainer
The id of the containing element of the element with the results/suggestions.
charactersBeforeSearch
The number of characters has to be higher than this value to perform a search.
timeBeforeSuggest
The time, in milliseconds, before a suggestion is made.
sameWidthAsInputElm
If the suggestions' containing element should have the same width as the input element that contains the characters to search for.
offsetLeft
The suggestions element is always placed at the same position from the left and ust below the input element containing the search term. This value can be added/substracted from that.
offsetTop
The suggestions element is always placed at the same position from the left and ust below the input element containing the search term. This value can be added/substracted from that.
urlExt
What query string that should be added to the URL used for the AJAX call. End it with an equal sign = if you set the addSearchTermToQueryString property to true.
addSearchTermToQueryString
If the actual characters being searched for should be added to the query string. Make sure to end the urlExt property with an equal sign = if this is set to true.
addKeyNavigationEvents
If it should be possible to navigate the suggestions with the arrow keys on the keyboard, adn to hide it with Esc.
hideResultsOnDocumentClick
If a click on the document should hide the results list.
itemClassName
CSS class name used for navigation items in the suggestions.
itemSelectedClassName
CSS class name used for the selected navigation item in the suggestions.
itemInsertValueIntoInputClassName
CSS class used for those items in the navigation list, where a selection of them would put the value of their href attibute in the input element that contains the search term/-s.
itemInsertValueSetFocusToInput
If the focus should be set to the input element, once an item has updated the input element's value (by initially having the itemInsertValueIntoInputClassName CSS class).
hideResultsWhenInsertValueIsSelected
If the results list should be hidden when the input element's value is updated.
itemSeparator
Character separating multiple choices amongst the navigation items, when they're placed in the input element containing the search term/-s.
turnAutoCompleteOff
Turns off autocompletion for the input element, if set to true.