/twitter-bootstrap-typeahead

An extension of Twitter's Bootstrap Typeahead plugin with additional customisation.

Primary LanguageJavaScriptMIT LicenseMIT

Twitter Bootstrap Typeahead Plugin Extension

UPDATE (Feb 21, 2013)

I no longer have the time to maintain this plugin. If you are looking for updated code, please take a look at the following to help you:

v1.2.2
Terry Rosen @rerrify

An extension of the Twitter Bootstrap Typeahead plugin
http://twitter.github.com/bootstrap/javascript.html#typeahead

About

All the thanks in the world to @mdo and @fat of @twitter for the wonderful Bootstrap utility.
I required more functionality out of the Typeahead plugin so I created this extension with some additional features:

  • A callback function is available for when an item is selected
  • Ability to specify data source properties
  • Ability to use a local or remote (AJAX) data source
  • Most original methods are overridable so you can customize without changing the source code

Required

  • Twitter Bootstrap 2.0+
  • jQuery 1.7+

Installation

  1. Download Bootstrap & jQuery

  2. Download this plugin.

  1. Include files in your HTML. The minimum required for this plugin are:

    <script src="/path/to/jquery.js" type="text/javascript"></script> <script src="/path/to/bootstrap-typeahead.js" type="text/javascript"></script>

  2. Execute the plugin:

    $(myElement).typeahead(options);

Events

Event Description
grepper Filters relevant results from the source.
highlighter Highlights any matching results in the list.
itemSelected The callback function that is invoked when an item is chosen.
  • item: the HTML element that was selected
  • val: value of the *val* property
  • text: value of the *display* property
lookup Determines if source is remote or local and initializes the search.
matcher Looks for a match between the query and a source item.
render Renders the list of results.
select Selects an item from the results list.
sorter Sorts the results.

Options

Name Type Default Description
ajax object 
{
    url: null,
    timeout: 300,
    method: 'post',
    triggerLength: 3,
    loadingClass: null,
    displayField: null,
    preDispatch: null,
    preProcess: null
}
 The object required to use a remote datasource.
See also: ajax as a string (below)
ajax string null Optionally, a simple URL may be used instead of the AJAX object.
See also: ajax as an object (above)
display string 'name' The object property to match the query against and highlight in the results.
item string '<li><a href="#"></a></li>' The HTML rendering for a result item.
items integer 8 The maximum number of items to show in the results.
menu string '<ul class="typeahead dropdown-menu"></ul>' The HTML rendering for the results list.
source object [] The source to search against.
val string 'id' The object property that is returned when an item is selected.

Basic Usage

The plugin in its simplest (realistic) form.

var mySource = [{ id: 1, name: 'Terry'}, { id: 2, name: 'Mark'}, { id: 3, name: 'Jacob'}];

$('#myElement').typeahead({
	source: mySource
});

Or using a remote data source:

$('#myElement').typeahead({
    ajax: '/path/to/mySource'
});

Examples demonstrating various options are included in this project under the /demo folder

Why did you change so much from v1.0 to v1.1?

I found certain things to be redundant, like having separate sort and display properties. I can't think of a reasonable scenerio where you would be sorting based on something different than what you are displaying.

What the $#&* did you do to the source code?

I added comments, semi-colons and other formatting that I like to use based on idiomatic JS guidelines.

If you are concerned with the bigger file size, you should always be minifying your JS before production use.

Change Log

1.2.2

  • Added support for jQuery 1.8 & Bootstrap 2.1
  • Removed usage of jQuery.browser #9385
  • Changed jQuery.data() to jQuery._data() in order to make test suite operational #11718
  • Added an undocumented function eventSupported(eventName) to verify browser support for keydown event. You may override this function if you prefer to do this check another way.

1.2.1

  • Some AJAX tests added
  • Added fix for spontaneous AJAX bug reported by users
  • grepper and lookup methods are now overridable

1.2

  • Added AJAX support

1.1

  • Major code cleanup
  • Test cases added
  • Documentation improvements

Road Map

1.3

  • Add template support