Merge branch 'readme-0.9.0' of git://github.com/jharding/typeahead.js…

… into integration-0.9.0

Conflicts:
	README.md

README.md

@@ -8,16 +8,16 @@ Inspired by [twitter.com][twitter]'s autocomplete search functionality, typeahea
 Getting Started
 ---------------
 
-typeahead.js consists of *typeahead.js* and *typeahead.css*. How you acquire those files is up to you.
+How you acquire typeahead.js is up to you.
 
 Preferred method:
 * Install with [Bower][bower]: `$ bower install typeahead.js`
 
-Manual methods:
+Other methods:
 * [Download zipball of latest release][zipball].
-* Download latest [typeahead.js][typeahead.js] and [typeahead.css][typeahead.css] individually.
+* Download latest *[typeahead.js][typeahead.js]* or *[typeahead.min.js][typeahead.min.js]*.
 
-**Note:** typeahead.js has a dependency on [jQuery][jQuery] 1.9+, it must be loaded before *typeahead.js*.
+**Note:** typeahead.js has a dependency on [jQuery][jquery] 1.9+, it must be loaded before *typeahead.js*.
 
 Examples
 --------
@@ -47,7 +47,7 @@ Usage
 
 #### jQuery#typeahead(datasets)
 
-Turns any `input[type="text"]` element into a typeahead. `datasets` is expected to be a single [dataset][datasets] or an array of datasets.
+Turns any `input[type="text"]` element into a typeahead. `datasets` is expected to be a single [dataset][dataset] or an array of datasets.
 
 ```javascript
 // single dataset
@@ -70,38 +70,48 @@ $('input.twitter-search').typeahead([
 ]);
 ```
 
-#### jQuery.fn.typeahead.configureTransport(options)
+#### jQuery#typeahead('destroy')
 
-Configures the transport component that will be used by typeaheads initialized with the `remote` property set. Once `jQuery#typeahead` is called, this function will not be accessible. Refer to [Transport][transport] for an overview of the transport component along with the details of the configurable options.
+Destroys previously initialized typeaheads. This entails reverting DOM modifications and removing event handlers.
 
 ```javascript
-$.fn.typeahead.configureTransport({
-  debounce: true,
-  maxConcurrentRequests: 6
+$('input.typeahead-devs').typeahead({
+  name: 'accounts',
+  local: ['timtrueman', 'JakeHarding', 'vskarich']
 });
+
+$('input.typeahead-devs').typeahead('destroy');
 ```
 
-### Datasets
+### Dataset
+
+A dataset is an object that defines a set of data that hydrates suggestions. Typeaheads can be backed by multiple datasets. Given a query, a typeahead instance will inspect its backing datasets and display relevant suggestions to the end-user. 
+
+When defining a dataset, the following options are available:
+
+* `name` – The string used to identify the dataset. Used by typeahead.js to cache intelligently.
+
+* `valueKey` – The key used to access the value of the datum in the datum object. Defaults to `value`.
 
-Datasets are objects which define the sets of data that hydrate suggestions. Given a query, a typeahead instance will inspect its backing datasets and display relevant suggestions to the end-user. Below are the options available for configuring a dataset.
+* `limit` – The max number of suggestions from the dataset to display for a given query. Defaults to `5`.
 
-* `name` - The string used to identify the dataset.
+* `template` – The template used to render suggestions. If not provided, suggestions will render as their value contained in a `<p>` element (i.e. `<p>value</p>`).
 
-* `limit` - The max number of suggestions from the dataset to display for a given query. Defaults to `5`.
+* `engine` – The template engine used to compile/render `template`. Any engine can use used as long as it adheres to the [expected API][template-engine-compatibility]. **Required** if `template` is set.
 
-* `template` - The template used to render suggestions. If not provided, suggestions will render as their value contained in a `<p>` element (i.e. `<p>value</p>`).
+* `header` – The header rendered before suggestions in the dropdown menu. Can be either a DOM element or HTML.
 
-* `engine` - The template engine used to compile/render `template`. Any engine can be used as long as it adheres to the [expected API][template-engine-compatibility]. **Required** if `template` is set.
+* `footer` – The footer rendered after suggestions in the dropdown menu. Can be either a DOM element or HTML.
 
-* `local` - An array of [datums][datums].
+* `local` – An array of [datums][datum].
 
-* `prefetch` - A URL to a JSON file containing an array of datums.
+* `prefetch` – Can be a URL to a JSON file containing an array of datums or, if more configurability is needed, a [prefetch options object][prefetch].
 
-* `remote` - A URL to fetch suggestions from when the data provided by `local` and `prefetch` is insufficient for a given query. If the URL contains the wildcard configurable through the [transport options][transport], said wildcard will be replaced with the end-user's query before the request is made.
+* `remote` – Can be a URL to fetch suggestions from when the data provided by `local` and `prefetch` is insufficient or, if more configurability is needed, a [remote options object][remote].
 
-### Datums
+### Datum
 
-Datums are the individual units that compose datasets. The canonical form of a datum is an object with a `value` property and a `tokens` property. `value` is the string that represents the underlying value of the datum and `tokens` is a collection of strings that aid typeahead.js in matching datums with a given query.
+The individual units that compose datasets are called datums. The canonical form of a datum is an object with a `value` property and a `tokens` property. `value` is the string that represents the underlying value of the datum and `tokens` is a collection of strings that aid typeahead.js in matching datums with a given query.
 
 ```javascript
 {
@@ -110,7 +120,7 @@ Datums are the individual units that compose datasets. The canonical form of a d
 }
 ```
 
-For ease of use, datums can also be represented as a string. Strings found in place of datum objects are converted to a datum object whose value is the found string and with tokens equal to the value split by whitespace.
+For ease of use, datums can also be represented as a string. Strings found in place of datum objects are implicitly converted to a datum object.
 
 When datums are rendered as suggestions, the datum object is the context passed to the template engine. This means if you include any arbitrary properties in datum objects, those properties will be available to the template used to render suggestions.
 
@@ -128,18 +138,60 @@ When datums are rendered as suggestions, the datum object is the context passed
 }
 ```
 
-### Transport
+### Prefetch
+
+Prefetched data is fetched and processed on initialization. If the browser supports localStorage, the processed data will be cached there to prevent additional network requests on subsequent page loads.
+
+When configuring `prefetch`, the following options are available:
+
+* `url` – A URL to a JSON file containing an array of datums. **Required.**
+
+* `ttl` – The time (in milliseconds) the prefetched data should be cached in localStorage. Defaults to `86400000` (1 day).
+
+* `filter` – A function with the signature `filter(parsedResponse)` that transforms the response body into an array of datums. Expected to return an array of datums.
+
+
+### Remote
 
-The transport component is a singleton used by all typeaheads initialized with the `remote` property set. Its primary purpose is to rate-limit network requests and to manage the number of concurrent requests. Below are the options available for configuring the transport component.
+Remote data is only used when the data provided by `local` and `prefetch` is insufficient. In order to prevent an obscene number of requests being made to remote endpoint, typeahead.js rate-limits remote requests.
 
-* `rateLimitFn` - The function that will be used for rate-limiting network requests. Can be either `debounce` or `throttle`. Defaults to `debounce`.
+When configuring `remote`, the following options are available:
 
-* `wait` - The time interval in milliseconds that will be used by `rateLimitFn`. Defaults to `300`.
+* `url` – A URL to make requests to when when the data provided by `local` and `prefetch` is insufficient. **Required.**
 
-* `wildcard` - The pattern in the `remote` URL that will be replaced with the user's query when a request is made. Defaults to `%QUERY`.
+* `dataType` – The type of data you're expecting from the server. See the [jQuery.ajax docs][jquery-ajax] for more info. Defaults to `json`.
 
-* `maxConcurrentRequests` - The max number of AJAX requests typeahead.js can have pending. Defaults to `6`.
+* `cache` – Determines whether or not the browser will cache responses. See the [jQuery.ajax docs][jquery-ajax] for more info.
 
+* `timeout` – Sets a timeout for requests. See the [jQuery.ajax docs][jquery-ajax] for more info.
+
+* `wildcard` – The pattern in `url` that will be replaced with the user's query when a request is made. Defaults to `%QUERY`.
+
+* `replace` – A function with the signature `replace(url, uriEncodedQuery)` that can be used to override the request URL. Expected to return a valid URL. If set, no wildcard substitution will be performed on `url`.
+
+* `rateLimitFn` – The function used for rate-limiting network requests. Can be either `debounce` or `throttle`. Defaults to `debounce`.
+
+* `rateLimitWait` – The time interval in milliseconds that will be used by `rateLimitFn`. Defaults to `300`.
+
+* `maxParallelRequests` – The max number of parallel requests typeahead.js can have pending. Defaults to `6`.
+
+* `beforeSend` – A pre-request callback with the signature `beforeSend(jqXhr, settings)`. Can be used to set custom headers. See the [jQuery.ajax docs][jquery-ajax] for more info.
+
+* `filter` – A function with the signature `filter(parsedResponse)` that transforms the response body into an array of datums. Expected to return an array of datums.
+
+### Custom Events
+
+typeahead.js triggers the following custom events:
+
+* `typeahead:initialized` – Triggered after initialization. If data needs to be prefetched, this event will not be triggered until after the prefetched data is processed.
+
+* `typeahead:opened` – Triggered when the dropdown menu of a typeahead is opened.
+
+* `typeahead:closed` – Triggered when the dropdown menu of a typeahead is closed.
+
+* `typeahead:selected` – Triggered when a suggestion from the dropdown menu is explicitly selected. The datum for the selected suggestion is passed to the event handler as an argument.
+
+All custom events are triggered on the element initialized as a typeahead.
 
 ### Template Engine Compatibility
 
@@ -158,21 +210,24 @@ Check out [Hogan.js][hogan.js] if you're looking for a compatible mustache templ
 
 ### Look and Feel
 
-The purpose of the CSS file required by typeahead.js (i.e. *typeahead.css*) is to position the hint and dropdown menu components of typeaheads. It should not alter the appearance of the `input[type="text"]` it is called on.
+The styles applied by typeahead.js are for positioning the hint and the dropdown menu, no other styles should be affected. In most cases the styles applied by typeahead.js will work like a charm, but there are edge cases where some custom styles will be necessary. If you're having CSS issues, create an [issue][issues] or tweet [@typeahead][@typeahead] for support.
 
 By default, the dropdown menu created by typeahead.js is going to look ugly and you'll want to style it to ensure it fits into the theme of your web page. Below is a Mustache template describing the DOM structure of a typeahead.js dropdown menu. Note that the `{{{html}}}` tag is the HTML generated by the custom template you provide when defining datasets.
 
 ```html
-<ol class="tt-dropdown-menu">
+<span class="tt-dropdown-menu">
   {{#dataset}}
-    <li class="tt-dataset-{{name}}">
-      <ol class="tt-suggestions">
+    {{{header}}}
+    <div class="tt-dataset-{{name}}">
+      <span class="tt-suggestions">
         {{#suggestions}}
-          <li class="tt-suggestion">{{{html}}}<li>
+          <div class="tt-suggestion">{{{html}}}</div>
         {{/suggestions}}
-      </ol>
+      </span>
+    </div>
+    {{{footer}}}
   {{/dataset}}
-</ol>
+</span>
 ```
 
 When an end-user mouses or keys over a `.tt-suggestion`, the class `tt-is-under-cursor` will be added to it. You can use this class as a hook for styling the "under cursor" state of suggestions.
@@ -185,18 +240,19 @@ For simple autocomplete use cases, the typeahead component [Bootstrap][bootstrap
 * If you're customizing Bootstrap, exclude the typeahead component. If you're depending on the standard *bootstrap.js*, ensure *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.js-bootstrap.css] in order to get the typeahead.js dropdown menu to fit the default Bootstrap theme.
 
-Possible Future Work
---------------------
+Browser Support
+---------------
 
-* Mobile support
-* Benchmarking tool
-* Logging and analytics hooks
-* Backend component
+* Chrome
+* Firefox 3.5+
+* Safari 4+
+* Internet Explorer 7+
+* Opera 11+
 
 Issues
 ------
 
-Have a bug? Please create an issue here on GitHub!
+Discovered a bug? Please create an issue here on GitHub!
 
 https://github.com/twitter/typeahead.js/issues
 
@@ -225,17 +281,15 @@ Developers
 
 If you plan on contributing to typeahead.js, be sure to read the [contributing guidelines][contributing-guidelines].
 
-In order to build and test typeahead.js, you'll need to install its devDependencies (`$ npm install`) and have [grunt-cli][grunt-cli] installed (`$ npm install -g grunt-cli`). Below is an overview of the available Grunt tasks that'll be useful in development.
+In order to build and test typeahead.js, you'll need to install its dev dependencies (`$ npm install`) and have [grunt-cli][grunt-cli] installed (`$ npm install -g grunt-cli`). Below is an overview of the available Grunt tasks that'll be useful in development.
 
-* `grunt build` - Builds *typeahead.js* and *typeahead.css* from source.
-* `grunt build:js` - Builds *typeahead.js* from source.
-* `grunt build:css` - Builds *typeahead.css* from source.
-* `grunt lint` - Runs source and test files through JSHint.
-* `grunt test` - Runs the test suite with PhantomJS.
-* `grunt test:browser` - Runs the test suite in your default browser.
-* `grunt watch` - Rebuilds *typeahead.js* whenever a source file is modified.
-* `grunt server` - Serves files from the root of typeahead.js on localhost:8888. Useful for using *test/playground.html* for debugging/testing.
-* `grunt dev` - Runs `grunt watch` and `grunt server` in parallel.
+* `grunt build` – Builds *typeahead.js* from source.
+* `grunt lint` – Runs source and test files through JSHint.
+* `grunt test` – Runs the test suite with PhantomJS.
+* `grunt test:browser` – Runs the test suite in your default browser.
+* `grunt watch` – Rebuilds *typeahead.js* whenever a source file is modified.
+* `grunt server` – Serves files from the root of typeahead.js on localhost:8888. Useful for using *test/playground.html* for debugging/testing.
+* `grunt dev` – Runs `grunt watch` and `grunt server` in parallel.
 
 Authors
 -------
@@ -249,12 +303,12 @@ Shoutouts!
 
 Thanks for assistance and contributions:
 
-+ [@fat](https://github.com/fat)
-+ [@garann](https://github.com/garann)
-+ [@paulirish](https://github.com/paulirish)
-+ [@sindresorhus](https://github.com/sindresorhus)
-+ [@thisguy](https://twitter.com/thisguy)
-+ [And many others!][contributors]
+* [@fat](https://github.com/fat)
+* [@garann](https://github.com/garann)
+* [@paulirish](https://github.com/paulirish)
+* [@sindresorhus](https://github.com/sindresorhus)
+* [@thisguy](https://twitter.com/thisguy)
+* [And many others!][contributors]
 
 License
 -------
@@ -266,29 +320,34 @@ Licensed under the MIT License
 [twitter]: https://twitter.com
 [gh-page]: http://twitter.github.com/typeahead.js
 [examples]: http://twitter.github.com/typeahead.js/examples
+[@typeahead]: https://twitter.com/typeahead
 
 <!-- assets -->
 [zipball]: http://twitter.github.com/typeahead.js/releases/latest/typeahead.js.zip
 [typeahead.js]: http://twitter.github.com/typeahead.js/releases/latest/typeahead.js
-[typeahead.css]: http://twitter.github.com/typeahead.js/releases/latest/typeahead.css
+[typeahead.min.js]: http://twitter.github.com/typeahead.js/releases/latest/typeahead.min.js
 
 <!-- github links -->
 [contributing-guidelines]: https://github.com/jharding/ghostwriter/blob/master/CONTRIBUTING.md
 [compatible-template-engines]: https://github.com/twitter/typeahead/wiki/Compatible-Template-Engines
 [contributors]: https://github.com/twitter/typeahead.js/contributors
+[issues]: https://github.com/twitter/typeahead.js/issues
 
 <!-- deep links -->
 [features]: #features
 [transport]: #transport
-[datasets]: #datasets
-[datums]: #datums
+[dataset]: #dataset
+[prefetch]: #prefetch
+[remote]: #remote
+[datum]: #datum
 [template-engine-compatibility]: #template-engine-compatibility
 
 <!-- links to third party projects -->
 [jasmine]: http://pivotal.github.com/jasmine/
 [grunt-cli]: https://github.com/gruntjs/grunt-cli
 [bower]: http://twitter.github.com/bower/
 [jQuery]: http://jquery.com/
+[jquery-ajax]: http://api.jquery.com/jQuery.ajax/
 [hogan.js]: http://twitter.github.com/hogan.js/
 [bootstrap]: http://twitter.github.com/bootstrap/
 [typeahead.js-bootstrap.css]: https://github.com/jharding/typeahead.js-bootstrap.css