Migrating to typeahead.js v0.10.0
=================================

Preamble
--------

v0.10.0 of typeahead.js ended up being almost a complete rewrite. Many things 
stayed the same, but there were a handful of changes you need to be aware of 
if you plan on upgrading from an older version. This document aims to call out 
those changes and explain what you need to do in order to have an painless 
upgrade.

Notable Changes
----------------

### First Argument to the jQuery Plugin

In v0.10.0, the first argument to `jQuery#typeahead` is an options hash that
can be used to configure the behavior of the typeahead. This is in contrast
to previous versions where `jQuery#typeahead` expected just a series of datasets
to be passed to it:

```javascript
// pre-v0.10.0
$('.typeahead').typeahead(myDataset);

// v0.10.0
$('.typeahead').typeahead({
  highlight: true,
  hint: false
}, myDataset);
```

If you're fine with the default configuration, you can just pass `null` as the 
first argument:

```javascript
$('.typeahead').typeahead(null, myDataset);
```

### Bloodhound Suggestion Engine

The most notable change in v0.10.0 is that typeahead.js has been decomposed into
a suggestion engine and a UI view. As part of this change, the way you configure
datasets has changed. Previously, a dataset config would have looked like:

```javascript
{
  valueKey: 'num',
  local: [{ num: 'one' }, { num: 'two' }, { num: 'three' }],
  prefetch: '/prefetch',
  remote: '/remote?q=%QUERY'
}
```

In v0.10.0, an equivalent dataset config would look like:

```javascript
{
 displayKey: 'num',
 source: mySource
}
```

As you can see, `local`, `prefetch`, and `remote` are no longer defined at the 
dataset level. Instead, all you set in a dataset config is `source`. `source` is
expected to be a function with the signature `function(query, callback)`. When a
typeahead's query changes, suggestions will be requested from  `source`. It's
expected `source` will compute the suggestion set and invoke `callback` with an array
of suggestion objects. The typeahead will then go on to render those suggestions.

If you're wondering if you can still configure `local`, `prefetch`, and 
`remote`, don't worry, that's where the Bloodhound suggestion engine comes in.
Here's how you would define `mySource` which was referenced in the previous 
code snippet:

```
var mySource = new Bloodhound({
  datumTokenizer: function(d) { 
    return Bloodhound.tokenizers.whitespace(d.num); 
  },
  queryTokenizer: Bloodhound.tokenizers.whitespace,
  local: [{ num: 'one' }, { num: 'two' }, { num: 'three' }],
  prefetch: '/prefetch',
  remote: '/remote?q=%QUERY'
});

// this kicks off the loading and processing of local and prefetch data
// the suggestion engine will be useless until it is initialized
mySource.initialize();
```

In the above snippet, a Bloodhound suggestion engine is initialized and that's 
what will be used as the source of your dataset. There's still one last thing
that needs to be done before you can use a Bloodhound suggestion engine as the 
source of a dataset. Because datasets expect `source` to be function, the 
Bloodhound instance needs to be wrapped in an adapter so it can meet that 
expectation.

```
mySource = mySource.ttAdapter();
```

Put it all together:

```javascript
var mySource = new Bloodhound({
  datumTokenizer: function(d) { 
    return Bloodhound.tokenizers.whitespace(d.num); 
  },
  queryTokenizer: Bloodhound.tokenizers.whitespace,
  local: [{ num: 'one' }, { num: 'two' }, { num: 'three' }],
  prefetch: '/prefetch',
  remote: '/remote?q=%QUERY'
});

mySource.initialize();

$('.typeahead').typeahead(null, {
  displayKey: 'num',
  source: mySource.ttAdapter()
});
```

### Tokenization Methods Must Be Provided

The Bloodhound suggestion engine is token-based, so how datums and queries are
tokenized plays a vital role in the quality of search results. Pre-v0.10.0,
it was not possible to configure the tokenization method. Starting in v0.10.0,
you **must** specify how you want datums and queries tokenized. 

The most common tokenization methods split a given string on whitespace or 
non-word characters. Bloodhound provides implementations for those methods
out of the box:

```javascript
// returns ['one', 'two', 'twenty-five']
Bloodhound.tokenizers.whitespace('  one two  twenty-five');

// returns ['one', 'two', 'twenty', 'five']
Bloodhound.tokenizers.nonword('  one two  twenty-five');
```

For query tokenization, you'll probably want to use one of the above methods.
For datum tokenization, this is where you may want to do something a tad bit
more advanced.

For datums, sometimes you want tokens to be dervied from more than one property. 
For example, if you were building a search engine for GitHub repositories, it'd 
probably be wise to have tokens derived from the repo's name, owner, and 
primary language:

```javascript
var repos = [
  { name: 'example', owner: 'John Doe', language: 'JavaScript' },
  { name: 'another example', owner: 'Joe Doe', language: 'Scala' }
];

function customTokenizer(datum) {
  var nameTokens = Bloodhound.tokenizers.whitespace(datum.name);
  var ownerTokens = Bloodhound.tokenizers.whitespace(datum.owner);
  var languageTokens = Bloodhound.tokenizers.whitespace(datum.language);

  return nameTokens.concat(ownerTokens).concat(languageTokens);
}
```

There may also be the scenario where you want datum tokenization to be performed
on the backend. The best way to do that is to just add a property to your datums 
that contains those tokens. You can then provide a tokenizer that just returns 
the already existing tokens:

```javascript
var sports = [
  { value: 'football', tokens: ['football', 'pigskin'] },
  { value: 'basketball', tokens: ['basketball', 'bball'] }
];

function customTokenizer(datum) { return datum.tokens; }
```

There are plenty of other ways you could go about tokenizing datums, it really
just depends on what you are trying to accomplish.

### String Datums Are No Longer Supported

Dropping support for string datums was a difficult choice, but in the end it
made sense for a number of reasons. If you still want to hydrate the suggestion 
engine with string datums, you'll need to use the `filter` function:

```javascript
var engine = new Bloodhound({
  prefetch: {
    url: '/data',
    filter: function(data) {
      // assume data is an array of strings e.g. ['one', 'two', 'three']
      return $.map(data, function(str) { return { value: str }; });
    },
    datumTokenizer: function(d) { 
      return Bloodhound.tokenizers.whitespace(d.value); 
    },
    queryTokenizer: Bloodhound.tokenizers.whitespace
  }
});
```

### Precompiled Templates Are Now Required

In previous versions of typeahead.js, you could specify a string template along
with the templating engine that should be used to compile/render it. In 
v0.10.0, you can no longer specify templating engines; instead you must provide
precompiled templates. Precompiled templates are functions that take one 
argument: the context the template should be rendered with. 

Most of the popular templating engines allow for the creation of precompiled 
templates. For example, you can generate one using Handlebars by doing the
following:

```javascript
var precompiledTemplate = Handlebars.compile('<p>{{value}}</p>');
```

[Handlebars]: http://handlebarsjs.com/

### CSS Class Changes

`tt-is-under-cursor` is now `tt-cursor` - Applied to a hovered-on suggestion (either via cursor or arrow key).

`tt-query` is now `tt-input` - Applied to the typeahead input field.

Something Missing?
------------------

If something is missing from this migration guide, pull requests are accepted :)