ember-aupac-typeahead
Version:
typeahead.js for ember
212 lines (161 loc) • 11.6 kB
Markdown
# ember-aupac-typeahead
[](https://www.npmjs.com/package/ember-aupac-typeahead) [](https://travis-ci.org/aupac/ember-aupac-typeahead) [](http://emberobserver.com/addons/ember-aupac-typeahead)
A [typeahead.js](https://twitter.github.io/typeahead.js/) autocomplete for ember.
Updated to work with maintained fork [corejs-typeahead](https://github.com/corejavascript/typeahead.js))
- supports any datasource let it be local or remote.
- explicit support for ember-data via the `aupac-ember-data-typeahead` component.
- very customisable to meet your needs.
Demo [HERE](http://aupac.github.io/ember-aupac-typeahead/)
## Installation
`ember install ember-aupac-typeahead`
## Prerequisites
* `ember-data` > 1.13.x if using the `aupac-ember-data-typeahead` component
* `ember.js` > 1.13.x
## `aupac-ember-data-typeahead` component
The `aupac-ember-data-typeahead` component is an extension of the more generic `aupac-typeahead` and assumes you're using ember-data to retrieve your data remotely. This allows ember-data users to streamline the use of this component into a single line of code in their template.
#### Component Attributes
By default, each ember-data model supplied in `modelClass` is required to have a `displayName` (computed property or attribute) that will return a string representing the name to display in the suggestion template. If this is not possible you can override the `suggestionTemplate` and supply something else (see below).
In addition to all the features supported by `aupac-typeahead` (see below), `aupac-ember-data-typeahead` supports the following:
- `modelClass` : (*required) the dasherized form of the ember-data model you're searching for. ie 'customer-address'
- `displayKey` : (default: 'displayName') the attribute to display to the user when an item is selected,
- `params` : (default: {}) an object containing various query string parameters to send along with the remote request,
- `queryKey`: (default: 'q') the query parameter sent to the server containing the search text.
- `selection` : (default: null) initial selection - can be an `ember-data` model (in which case the `displayKey` is used as the initial value) or a `string` which will display as is. Wrap selection in `(readonly x)` helper to avoid two-way binding.
This component has already implemented the relevant functions to make them compatible with ember-data. You do not need to do so yourself.
#### Usage example
```html
<!--In this case the ember-data model "task" needs a displayName attribute-->
{{aupac-ember-data-typeahead modelClass='task' action=(action (mut selection))}}
```
The above is all you need to have a fully functional autocomplete search in your page. It would create an input that allows you to search for tasks and when selected would update the `selection` property on your controller.
## `aupac-typeahead` component
The `aupac-typeahead` component contains no assumptions about how you're retrieving your data. Both local and remote suggestions are supported.
#### Component Attributes
- `disabled` : (deafult: false) true if the control should be disabled.
- `placeholder` : (default: 'Search') the placeholder text to display in the input.
- `name` : (default: '') the name of the typeahead input.
- `action`: (*required) the selected item will be provided as the first argument.
- `selection` : (default: null) will be set as the initial selection in the component. Wrap selection with helper `(readonly x)` to avoid two-way binding.
- `autoFocus`: (default: false) focus the control on render.
- `transformSelection`: (default: no transform) allows you to transform the selected value before it is set on the typeahead by returning the transformed value, signature `function(selection)`
- `allowFreeInput`: (default: false) allows the user to input their own values that are not part of the option list. Only useful if the item being selected is a String.
- `tabindex`: allows you to define a numeric tab index for the input
See the [typeahead docs](https://github.com/twitter/typeahead.js/blob/master/doc/jquery_typeahead.md#datasets) for a more complete description of the items below.
- `source` : (*required) a function to return an array of items to display to the user with the signature `function(query, syncResults, asyncResults)`. The callback functions `syncResults or asyncResults` should be called with an array of results as a parameter.
- `async` : (default: false) true if the returned data is asynchronous.
- `datasetName` : (default: 'default') the name of the dataset.
- `limit` : (default: 15) the maximum number of results to display to the user.
- `display` : (default: will display the returned item as is) function that displays the selected item to the user, signature `function(model)`.
- `suggestionTemplate` : a precompiled HTMLBars template used for suggestions, attribute bindings should be specified under the model object. ie `{{model.firstName}}`. If the returned value is **not** an object, it will be bound under {{model.displayName}}.
- `notFoundTemplate` : a precompiled HTMLBars template that is rendered when no results are found.
- `pendingTemplate` : a precompiled HTMLBars template that is rendered when loading the result set but not yet resolved.
- `headerTemplate` : a precompiled HTMLBars template displayed at the top of the search results.
- `footerTemplate` : a precompiled HTMLBars template displayed at the bottom of the search results.
See the [typeahead docs](https://github.com/twitter/typeahead.js/blob/master/doc/jquery_typeahead.md#options) for a more complete description of the items below.
- `highlight`: (default: true) true if matching text be highlighted in the search results.
- `hint`: (default: true) true if hints be displayed in the input.
- `minLength`: (default: 2) the minumum number of characters before a search in performed.
- `typeaheadClassNames`: (default: {}) allows you to customise the class names used in typeahead.
##### Example
In your template
```javascript
{{aupac-typeahead action=(action (mut country))
class='form-control'
source=countrySource
placeholder='Search for a country'}}
```
In your controller
```javascript
const countries = Ember.A(["Afghanistan","Albania","Algeria","Andorra","Angola","Anguilla","Antigua & Barbuda","Argentina","Armenia","Aruba","Australia","Austria","Azerbaijan","Bahamas"
,"Bahrain","Bangladesh","Barbados","Belarus","Belgium","Belize","Benin","Bermuda","Bhutan","Bolivia","Bosnia & Herzegovina","Botswana","Brazil","British Virgin Islands"
,"Brunei","Bulgaria","Burkina Faso","Burundi","Cambodia","Cameroon","Cape Verde","Cayman Islands","Chad","Chile","China","Colombia","Congo","Cook Islands","Costa Rica"
,"Cote D Ivoire","Croatia","Cruise Ship","Cuba","Cyprus","Czech Republic","Denmark","Djibouti","Dominica","Dominican Republic","Ecuador","Egypt","El Salvador","Equatorial Guinea"
,"Estonia","Ethiopia","Falkland Islands","Faroe Islands","Fiji","Finland","France","French Polynesia","French West Indies","Gabon","Gambia","Georgia","Germany","Ghana"
,"Gibraltar","Greece","Greenland","Grenada","Guam","Guatemala","Guernsey","Guinea","Guinea Bissau","Guyana","Haiti","Honduras","Hong Kong","Hungary","Iceland","India"
,"Indonesia","Iran","Iraq","Ireland","Isle of Man","Israel","Italy","Jamaica","Japan","Jersey","Jordan","Kazakhstan","Kenya","Kuwait","Kyrgyz Republic","Laos","Latvia"
,"Lebanon","Lesotho","Liberia","Libya","Liechtenstein","Lithuania","Luxembourg","Macau","Macedonia","Madagascar","Malawi","Malaysia","Maldives","Mali","Malta","Mauritania"
,"Mauritius","Mexico","Moldova","Monaco","Mongolia","Montenegro","Montserrat","Morocco","Mozambique","Namibia","Nepal","Netherlands","Netherlands Antilles","New Caledonia"
,"New Zealand","Nicaragua","Niger","Nigeria","Norway","Oman","Pakistan","Palestine","Panama","Papua New Guinea","Paraguay","Peru","Philippines","Poland","Portugal"
,"Puerto Rico","Qatar","Reunion","Romania","Russia","Rwanda","Saint Pierre & Miquelon","Samoa","San Marino","Satellite","Saudi Arabia","Senegal","Serbia","Seychelles"
,"Sierra Leone","Singapore","Slovakia","Slovenia","South Africa","South Korea","Spain","Sri Lanka","St Kitts & Nevis","St Lucia","St Vincent","St. Lucia","Sudan"
,"Suriname","Swaziland","Sweden","Switzerland","Syria","Taiwan","Tajikistan","Tanzania","Thailand","Timor L'Este","Togo","Tonga","Trinidad & Tobago","Tunisia"
,"Turkey","Turkmenistan","Turks & Caicos","Uganda","Ukraine","United Arab Emirates","United Kingdom","Uruguay","Uzbekistan","Venezuela","Vietnam","Virgin Islands (US)"
,"Yemen","Zambia","Zimbabwe"]);
export default Ember.Controller.extend({
country : null,
countrySource : function(query, syncResults, asyncResults) {
const regex = new RegExp(`.*${query}.*`, 'i');
const results = countries.filter((item, index, enumerable) => {
return regex.test(item);
})
syncResults(results);
}
});
```
## Using your own custom template
You can override the `suggestionTemplate`, `notFoundTemplate`, `pendingTemplate`, `headerTemplate` or `footerTemplate` used by importing a `*.hbs` file and assigning to the appropriate property.
For example
```handlebars
{{!-- app/templates/country-templates/suggestion.hbs --}}
<div class='typeahead-suggestion'><img src="http://www.gravatar.com/avatar/0cf15665a9146ba852bf042b0652780a?s=200" style="width: 10%; height: 10%">{{model.displayName}}</div>
```
Then in your controller
```javascript
import customSuggestionTemplate from '../templates/country-templates/suggestion';
export default Ember.Controller.extend({
customSuggestionTemplate: customSuggestionTemplate
})
```
And assign it to your template
```handlebars
{{aupac-typeahead action=(action (mut country))
... bind the custom suggestion template to the component
suggestionTemplate=customSuggestionTemplate
}}
````
## Using your own version of [typeahead.js](https://twitter.github.io/typeahead.js/)
You can disable the importing of typeahead.js by adding the following to your `/config/environment.js`
```javascript
'ember-aupac-typeahead' : {
includeTypeahead: false
}
```
The current compatible typeahead.js version is *v0.11.1*
## CSS Styling
By default, Bootstrap 3 compatible css styles are included with the addon, you can disable this by adding:
```javascript
'ember-aupac-typeahead' : {
includeCss: false
}
```
See the [typeahead.js docs](https://github.com/twitter/typeahead.js/blob/master/doc/jquery_typeahead.md#class-names) for applying your own custom styling.
## Testing
#### [ember-cli-page-object](https://github.com/san650/ember-cli-page-object) is supported
`test/pages/aupac-typeahead.js`
```javascript
export function typeahead(selector, options) {
return {
search : function(search) {
$(selector).val(search).trigger('input');
},
suggestions : collection({
scope: '', //Reset to global scope
itemScope: '.tt-suggestion',
item: {
select: clickable()
}
})
};
}
```
TODO - show example
## Running
* `ember server`
* Visit your app at http://localhost:4200.
## Running Tests
* `ember test`
* `ember test --server`
## Building
* `ember build`
For more information on using ember-cli, visit [http://www.ember-cli.com/](http://www.ember-cli.com/).