/bootstrap-ajax-typeahead

Twitter Bootstrap Ajax Typeahead Plugin

Primary LanguageJavaScript

Twitter Bootstrap Ajax Typeahead Plugin

Modifications to the Bootstrap Typeahead plugin to give it ajax capabilities

How to Use

To make a regular typeahead plugin query a server for the source, just specify an ajax member when initializing.

Required

  • Twitter Bootstrap 2.0+
  • jQuery 1.7+

Installation

Download jQuery

Download Bootstrap

Download this plugin.

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

<link href="/path/to/bootstrap.css" rel="stylesheet">
<script src="/path/to/jquery.js" type="text/javascript"></script>
<script src="/path/to/bootstrap-typeahead.js" type="text/javascript"></script>

Execute the plugin:

    $('input.typeahead').typeahead(options);

Events

Event Description
grepper Filters relevant results from the source.
highlighter Highlights any matching results in the list.
onSelect The callback function that is invoked when an item is chosen. 
{
   item : {
    value: "",
    text: ""
   }
}
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 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
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.

Ajax Options

Name Type Default Description
url string null 
    </td>
</tr>
<tr>
    <td>
        timeout
    </td>
    <td>
        integer
    </td>
    <td>
        300
    </td>
    <td>
        Specify the amount of time to wait for keyboard input to stop until you send the query to the server.
        Default is at 300ms.
    </td>
</tr>
<tr>
    <td>
        method
    </td>
<td>
        string
    </td>
<td>
        'get'
    </td>
    <td>
        The method to use, either "post" or "get".
    </td>
</tr>
<tr>
    <td>
        triggerLength
    </td>
<td>
        integer
    </td>
    <td>
        1
    </td>
    <td>
    This is the minimum length of text to take action on. Default is at 1.
    </td>
</tr>
<tr>
    <td>
        loadingClass
    </td>
<td>
        string
    </td>
    <td>
        null
    </td>
    <td>

    </td>
</tr>
<tr>
    <td>
        preDispatch
    </td>
<td>
        function
    </td>
    <td>
        null
    </td>
    <td>
This function will be run prior to any call. It is used to fashion a custom parameter
object to send to the server. Its only argument is the query text. It must return an
object that jQuery's post() function will use as its second argument. There's no default for this.
If not specified, the parameters send to the server are:
    <pre>
        { query: "some text" }
    </pre>
    </td>
</tr>
<tr>
    <td>
        preProcess
    </td>
<td>
        function
    </td>
    <td>
       null
    </td>
    <td>
This function will be run right after a call and before the typeahead list is populated.
It is used to pre process the data returned from the server. Its only argument is the data
from the server. Returning false from this method will hide the typeahead list.
If not specified, the data will be passed to the typeahead mechanism as is.
    </td>
</tr>
<tr>
    <td>
        displayField
    </td>
<td>
        string
    </td>
<td>
        'name'
    </td>
    <td>
    If the data returned from the server is a list of objects (as opposed to an array of strings),
    set this member to the name for the field to use for display.
    </td>
</tr>
<tr>
    <td>
        valueField
    </td>
<td>
        string
    </td>
<td>
        'id'
    </td>
    <td>
      If the data returned from the server is a list of objects (as opposed to an array of strings),
      set this member to the id data for the item into list (*required* for a list of objects).
    </td>
</tr>

Basic Usage

The plugin in its simplest (realistic) form.

var typeaheadSource = [{ id: 1, name: 'John'}, { id: 2, name: 'Alex'}, { id: 3, name: 'Terry'}];

$('input.typeahead').typeahead({
	source: typeaheadSource
});

For a quick setup, specify a source url to pull data from:

$('input.typeahead').typeahead({
        ajax: '/path/to/typeahead/source'
});

Extended Usage

$("input.typeahead").typeahead({
	onSelect: function(item) {
		console.log(item);
	},
	ajax: {
		url: "/path/to/source",
		timeout: 500,
		displayField: "title",
		triggerLength: 1,
		method: "get",
		loadingClass: "loading-circle",
		preDispatch: function (query) {
			showLoadingMask(true);
			return {
				search: query
			}
		},
		preProcess: function (data) {
			showLoadingMask(false);
			if (data.success === false) {
				// Hide the list, there was some error
				return false;
			}
			// We good!
			return data.mylist;
		}
	}
});

Bootstrap Integration

For simple autocomplete use cases, the typeahead component [Bootstrap][bootstrap] provides should suffice. However, if you'd prefer to take advantage of some of the advance features typeahead.js provides, here's what you'll need to do to integrate typeahead.js with Bootstrap:

  • If you're customizing Bootstrap, exclude the typeahead component. If you're depending on the standard bootstrap.js, ensure bootstrap-typeahead.js is loaded after it.
  • The DOM structure of the dropdown menu used by typeahead.js differs from the DOM structure of the Bootstrap dropdown menu. You'll need to load some [additional CSS][typeahead-bootstrap.css] in order to get the bootstrap-typeahead.js dropdown menu to fit the default Bootstrap theme.

Browser Support

  • Chrome
  • Firefox 3.5+
  • Safari 4+
  • Internet Explorer 7+
  • Opera 11+

Recommend extensions

Copyright and license

Copyright 2012 Twitter, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Resources