newmana / aaap Goto Github PK

Andrew's Ajax AutoComplete for Prototype (AAAP)
===============================================

This is an update/fork of:
http://www.devbridge.com/projects/autocomplete/

This adds some new functionality and removes some bugs.

How to Use
==========

The files used are:
style.css - the css styling.
shadow.png - used for the drop shadow effect.
autocomplate.js - the library.

Put the following into your HTML file (requires prototype) or add to
existing CSS and Javascript files:
<link rel="stylesheet" type="text/css" href="style.css"/>
<script type="text/javascript" src="autocomplete.js"></script>

Add to your Event observer:
Event.observe(window, 'load', function() {
  ...
  new Autocomplete("query", { 
    serviceUrl : "/object"
  ...
});

Add a form input tag:
<input type="text" name="wunderbar" id="query"/>

If you type "whateveryoutype" into the text bar then it will send a GET
request: 
/object?query=whateveryoutype

The server responds to the GET request with the following JSON:
{
  query:'whateveryoutyped',
  suggestions: [['a', 'person'], ['b'], ['c']],
  data: ['A', 'B', 'C']
}

Query - the query that was requested.
Suggestions - an array with the results to display from the query as the
 first element ('a', 'b', and 'c'). The second element being a class to add
 to the div (e.g. 'a' will have a div class called 'person', 'b' and 'c'
 will have none).
Data (optional) - values that are not visible but can be used to refer to 
 the visible results - like an ID - used in callback function when the
 result is selected.

Options when constructing Autocomplete:
* serverUrl - a URL to send the GET query to.
* parameters - allows named parameters or functions (to be executed each
 time) to be added to the Ajax request.
* onSelect - a function that will be called when a value a value is
 selected from the drop down (returned by the query).
* onNoResults - a function that is called when the query returns without any
 results.  Useful if you want to display that no results were found.
* onSuggestion - a function that is called when the query returns with
 suggestions.  Useful if you want to give a number of results.
* onKeypressed - a function that is called when the user modified the text
 box.  Useful if you want to clear error messages.
* maxHeight - the maximum number of pixels high that the drop down box will
 be. -1 will prevent a maximum height from being set.
* autoHide - true by default.  Acts as a drop down by default setting this
 to false means that the box will always be displayed.
* width - the number of pixels wide the drop down box will be.
* autoSubmit - set to true to submit the value without requiring the user 
 to hit enter or TAB.
* minChars - the number of characters to wait for the user to type before
 (re-)submitting the query.
* deferRequestBy - the number of milliseconds to wait before submitting the
 query.
* container - the name of the DIV that the box is in (if you want to inherit
 styles, etc).

Examples
========
To send an additional parameter and execute a function each time a request is sent:
new Autocomplete("query", {
  serviceUrl : "/object",
  parameters : {
    something : "foo",
    func : doStuff
  }
});

function doStuff() {
  ...
}

This will send:
/object?query=whateveryoutype&something=foo&func=resultOfDoStuff

Testing
=======
This uses Jasmine, to run the specs load: SpecRunner.html into your browser.

Changes
=======

Version 1.0.1
-------------
* Changed suggestions to be an array with an optional second element that
 adds a class to the divs in the drop down list.
* Disable maxHeight by settings it to -1.
* Added callback for suggestions.
* Added autoHide.
* Added ability to add/remove entries dynamically and keep original suggested
 order.

Version 1.0
-----------
* Fixes a bug when user click on the suggestion and then the user cannot search again. 
* Adds method onNoResults (when the AJAX query returns no results).
* Adds method onKeypressed (when user types something in to the text box).
* Doesn't allow submission (on Enter or TAB) if there are no results
 returned by the initial query.
* Added parameters for initial Ajax Request.
* Added ability to select text box and delete (and queries still work).
* Suggestions can contain extra information in brackets e.g. 
 "Javascript (language)" that will not show up in textbox.
* Added testing with Jasmine.