Subversion Repositories SmartDukaan

Bloodhound
==========

Bloodhound is the typeahead.js suggestion engine. Bloodhound is robust, 
flexible, and offers advanced functionalities such as prefetching, intelligent
caching, fast lookups, and backfilling with remote data.

Table of Contents
-----------------

* [Features](#features)
* [Usage](#usage)
  * [API](#api)
  * [Options](#options)
  * [Prefetch](#prefetch)
  * [Remote](#remote)
  * [Datums](#datums)
  * [Tokens](#tokens)

Features
--------

* Works with hardcoded data
* Prefetches data on initialization to reduce suggestion latency
* Uses local storage intelligently to cut down on network requests
* Backfills suggestions from a remote source
* Rate-limits and caches network requests to remote sources to lighten the load

Usage
-----

### API

#### new Bloodhound(options)

The constructor function. It takes an [options hash](#options) as its only 
argument.

```javascript
var engine = new Bloodhound({
  name: 'animals',
  local: [{ val: 'dog' }, { val: 'pig' }, { val: 'moose' }],
  remote: 'http://example.com/animals?q=%QUERY',
  datumTokenizer: function(d) {
    return Bloodhound.tokenizers.whitespace(d.val);
  },
  queryTokenizer: Bloodhound.tokenizers.whitespace
});
```

#### Bloodhound#initialize(reinitialize)

Kicks off the initialization of the suggestion engine. This includes processing 
the data provided through `local` and fetching/processing the data provided 
through `prefetch`. Until initialized, all other methods will behave as no-ops.
Returns a [jQuery promise] which is resolved when engine has been initialized.

```javascript
var promise = engine.initialize();

promise
.done(function() { console.log('success!'); })
.fail(function() { console.log('err!'); });
```

After the initial call of `initialize`, how subsequent invocations of the method
behave depends on the `reinitialize` argument. If `reinitialize` is falsy, the
method will not execute the initialization logic and will just return the same 
jQuery promise returned by the initial invocation. If `reinitialize` is truthy,
the method will behave as if it were being called for the first time.

```javascript
var promise1 = engine.initialize();
var promise2 = engine.initialize();
var promise3 = engine.initialize(true);

promise1 === promise2;
promise3 !== promise1 && promise3 !== promise2;
```

#### Bloodhound#add(datums)

Takes one argument, `datums`, which is expected to be an array of 
[datums](#datums). The passed in datums will get added to the search index that
powers the suggestion engine.

```javascript
engine.add([{ val: 'one' }, { val: 'two' }]);
```

#### Bloodhound#clear()

Removes all suggestions from the search index.

```javascript
engine.clear();
```

#### Bloodhound#clearPrefetchCache()

If you're using `prefetch`, data gets cached in local storage in an effort to
cut down on unnecessary network requests. `clearPrefetchCache` offers a way to
programmatically clear said cache.

```javascript
engine.clearPrefetchCache();
```

#### Bloodhound#clearRemoteCache()

If you're using `remote`, Bloodhound will cache the 10 most recent responses
in an effort to provide a better user experience. `clearRemoteCache` offers a 
way to programmatically clear said cache.

```javascript
engine.clearRemoteCache();
```

#### Bloodhound.noConflict()

Returns a reference to the Bloodhound constructor and reverts 
`window.Bloodhound` to its previous value. Can be used to avoid naming 
collisions. 

```javascript
var Dachshund = Bloodhound.noConflict();
```


<!-- section links -->

[jQuery promise]: http://api.jquery.com/Types/#Promise

#### Bloodhound#get(query, cb)

Computes a set of suggestions for `query`. `cb` will be invoked with an array
of datums that represent said set. `cb` will always be invoked once 
synchronously with suggestions that were available on the client. If those
suggestions are insufficient (# of suggestions is less than `limit`) and `remote` was configured, `cb` may also be 
invoked asynchronously with the suggestions available on the client mixed with
suggestions from the `remote` source.

```javascript
bloodhound.get(myQuery, function(suggestions) {
  suggestions.each(function(suggestion) { console.log(suggestion); });
});
```

### Options

When instantiating a Bloodhound suggestion engine, there are a number of 
options you can configure.

* `datumTokenizer` – A function with the signature `(datum)` that transforms a
  datum into an array of string tokens. **Required**.

* `queryTokenizer` – A function with the signature `(query)` that transforms a
  query into an array of string tokens. **Required**.

* `limit` – The max number of suggestions to return from `Bloodhound#get`. If 
  not reached, the data source will attempt to backfill the suggestions from 
  `remote`. Defaults to `5`.

* `dupDetector` – If set, this is expected to be a function with the signature 
  `(remoteMatch, localMatch)` that returns `true` if the datums are duplicates or 
  `false` otherwise. If not set, duplicate detection will not be performed.

* `sorter` – A [compare function] used to sort matched datums for a given query.

* `local` – An array of [datums](#datums) or a function that returns 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 hash](#prefetch).

* `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 hash](#remote).

<!-- section links -->

[compare function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort

### Prefetch

Prefetched data is fetched and processed on initialization. If the browser 
supports local storage, the processed data will be cached there to 
prevent additional network requests on subsequent page loads.

**WARNING:** While it's possible to get away with it for smaller data sets, 
prefetched data isn't meant to contain entire data sets. Rather, it should act 
as a first-level cache for suggestions. If don't keep this warning in mind, 
you run the risk of hitting [local storage limits].

When configuring `prefetch`, the following options are available.

* `url` – A URL to a JSON file containing an array of datums. **Required.**

* `cacheKey` – The key that data will be stored in local storage under. 
  Defaults to value of `url`.

* `ttl` – The time (in milliseconds) the prefetched data should be cached in 
  local storage. Defaults to `86400000` (1 day).

* `thumbprint` – A string used for thumbprinting prefetched data. If this
  doesn't match what's stored in local storage, the data will be refetched.

* `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.

* `ajax` – The [ajax settings object] passed to `jQuery.ajax`.

<!-- section links -->

[local storage limits]: http://stackoverflow.com/a/2989317
[ajax settings object]:http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings

### Remote

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
the remote endpoint, requests are rate-limited.

When configuring `remote`, the following options are available.

* `url` – A URL to make requests to when when the data provided by `local` and 
  `prefetch` is insufficient. **Required.**

* `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, query)` 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`.

* `rateLimitBy` – The method used to rate-limit network requests. Can be either 
  `debounce` or `throttle`. Defaults to `debounce`.

* `rateLimitWait` – The time interval in milliseconds that will be used by 
  `rateLimitBy`. Defaults to `300`.

* `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.

* `ajax` – The [ajax settings object] passed to `jQuery.ajax`.

<!-- section links -->

[ajax settings object]: http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings

### Datums

Datums are JavaScript objects that hydrate the pool of possible suggestions.
Bloodhound doesn't expect datums to contain any specific properties as any
operations performed on datums are done using functions defined by the user i.e.
`datumTokenizer`, `dupDetector`, and `sorter`.

### Tokens

The algorithm used by bloodhounds for providing suggestions for a given query 
is token-based. When `Bloodhound#get` is called, it tokenizes `query` using 
`queryTokenizer` and then invokes `cb` with all of the datums that contain those 
tokens.

For a quick example, if a datum was tokenized into the following set of 
tokens...

```javascript
['typeahead.js', 'typeahead', 'autocomplete', 'javascript'];
```

...it would be a valid match for queries such as:

* `typehead`
* `typehead.js`
* `autoco`
* `java type`