ember-aupac-typeahead
A typeahead.js autocomplete for ember.
- 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
Installation
ember install ember-aupac-typeahead
Prerequisites
ember-data
> 1.13.x if using theaupac-ember-data-typeahead
componentember.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 anember-data
model (in which case thedisplayKey
is used as the initial value) or astring
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
<!--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, signaturefunction(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.
See the typeahead docs 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 signaturefunction(query, syncResults, asyncResults)
. The callback functionssyncResults or asyncResults
should be called with and 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, signaturefunction(model)
.suggestionTemplate
: a precompiled HTMLBars template used for suggestions, attribute bindings should be specified under the model object. ie{{model.firstName}}
.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 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
{{aupac-typeahead action=(action (mut country))
class='form-control'
source=countrySource
placeholder='Search for a country'}}
In your controller
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
{{!-- 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}}</div>
Then in your controller
import customSuggestionTemplate from '../templates/country-templates/suggestion';
export default Ember.Controller.extend({
customSuggestionTemplate: customSuggestionTemplate
})
And assign it to your template
{{aupac-typeahead action=(action (mut country))
... bind the custom suggestion template to the component
suggestionTemplate=customSuggestionTemplate
}}
typeahead.js
Using your own version ofYou can disable the importing of typeahead.js by adding the following to your /config/environment.js
'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:
'ember-aupac-typeahead' : {
includeCss: false
}
See the typeahead.js docs for applying your own custom styling.
Testing
ember-cli-page-object is supported
test/pages/aupac-typeahead.js
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/.