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 theaddSearchTermToQueryString
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 theinput
element that contains the search term/-s. itemInsertValueSetFocusToInput
- If the focus should be set to the
input
element, once an item has updated theinput
element's value (by initially having theitemInsertValueIntoInputClassName
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.