##Overview

Typeahead.js is an overlay of Twitter typeahead.js and backbone.js that creates a Backbone.Layout view for a consistent rendering of any Backbone.Collection as a fast and extensible typeahead module.

##Example Usage

    this.typeahead = new HPITypeahead({
       	options: this.formTypes,
        displayKey: 'pageSetName',
        searchOn: 'pageSetName'
    });

    this.listenTo(this.typeahead, 'change:selected', function(option){
       	this.name = option ? option.value : undefined;
    }, this);

##events

this.listenTo(this.typeahead, 'change:selected') : Whenever a user selects an option from the typeahead (via autocomplete, tab, or selecting an option in the dropdown), typeahead.js will trigger a Backbone.Event change:selected which will return the full object from the backing backbone collection.

##methods

setOption: function(value, updateTypeahead) : utility method for programmatically setting the typeahead to a particular option. Its expected that value is the full datum of the option you want selected or a string if that string is the value, for example:

{
    displayValue: 'Draft',
    value: 'draft'
}

will set the typeahead to show Draft, or passing in the string 'draft' will find and display the Draft datum (passing in full objects is recommended for any custom objects that don't have a value attribute).

updateOptions(options) : a utility method for updating the backing collection of the typeahead instance using a primitive collection of js objects. A use case could be an input where you type in the first few characters of a username and typeahead updates to show any matching results.

clear : method for programmatically clearing the selected option from typeahead. change:selected is triggered to notify any listening delegates.

##attributes

options : a Backbone.Collection of JS objects such as this example:

new Backbone.Collection(
[
    {
        "label": "Draft",
        "value": "Draft"
    },
    {
        "label": "In Review",
        "value": "In Review"
    },
    {
        "label": "Pending Approval",
        "value": "Pending Approval"
    },
    {
        "label": "Approved",
        "value": "Approved"
    },
    {
        "label": "Effective",
        "value": "Effective"
    },
    {
        "label": "Superseded",
        "value": "Superseded"
    },
    {
        "label": "Cancelled",
        "value": "Cancelled"
    }
]
)

note: picklists are a common use case that typeahead readily supports as a drop-in replacement for a regular <select>.

selected : default selected option for the typeahead to start with placeholder : placeholder text to show the user (ex. 'search for controlled documents starting with') displayKey : configurable display attribute for each option (defaults to 'displayValue'). Useful if your objects don'r have a displayValue attribute like:

{
    'user_name': 'test_user',
    'display_name': 'Test User 001'
}

searchOn : configurable value attribute for each option (defaults to 'displayValue'). This may seem counter-intuitive, but in typeahead, users want to see that their query matches what results are coming back, hence displayValue is the default over value.