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 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

<!--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 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 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, signature function(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
}}

Using your own version of typeahead.js

You 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/.