ember-hypersearch
v0.2.0
Published
Hyperspeed real-time search with caching
Downloads
9
Readme
ember-hypersearch :dash:
Hyperspeed real-time search with caching
Existing addons that implement real-time typeahead search assume that your app already has all the data. ember-hypersearch
lets you query an endpoint directly, and caches results locally for better performance when the same query is repeated.
If you provide the addon with data, it will use that directly and does fuzzy search to find the item.
Compatibility
This addon is tested to work with Ember versions 1.13.x
and up. For versions < 2.0
, you will need to install the excellent ember-get-helper
addon as well.
Because native inputs
are used in this addon, you will need to provide your own template in order to use it on pre-Glimmer versions of Ember (basically anything below 1.13.x
). As this makes for poor testing ergonomics, we do not explicitly test for backwards compatibility please report any issues you might encounter to our issue tracker.
Usage
First, install the addon:
$ ember install ember-hypersearch
Then include the hyper-search
component in a template of your choice:
{{hyper-search
endpoint="/api/v1/users"
resultKey="email"
placeholder="Search by email"
selectResult=(action "selectResult")
handleResults=(action "handleResults")
}}
The component can also be used in block form, if you pass it a template:
{{#hyper-search
endpoint="/api/v1/users"
resultKey="name"
selectResult=(action "selectResult") as |hypersearch|}}
<form {{action "commit" on="submit"}}>
{{one-way-input
name="query"
type="text"
placeholder="Search for...
update=(action "search" target=hypersearch)
}}
<ul>
{{#each hypersearch.results as |result|}}
<li>
<span {{action (action "selectResult") result on="click"}}>
{{get result hypersearch.resultKey}}
</span>
</li>
{{/each}}
</ul>
<button type="submit">Submit</button>
</form>
{{/hyper-search}}
Note that this addon is designed to work with native inputs, so you will not need to use the {{input}}
helper.
Component API
minQueryLength: {Number}
Default: 3
The minimum length for a query before it fetches and returns results.
debounceRate: {Number}
Default: 0
If > 0
, requests to your endpoint will be debounced by this number of milliseconds to reduce the load on your API.
endpoint: {String}
Default: null
The URL for your endpoint. By default, hyper-search
will do a simple GET
request with q
as a query parameter.
If your endpoint requires a different setup, you should reopen/extend the component and override the request
method. For example:
import HyperSearch from 'ember-hypersearch';
export default HyperSearch.reopen({
request(query) {
// Your AJAX request here
// Must return a `Promise`
}
});
resultKey: {String}
Default: null
Results of the current query are displayed in a ul
element below the input
. If your result is an array of objects, you can optionally specify a key to display in the list of results.
placeholder: {String}
Default: null
An optional placeholder for the hypersearch input.
selectResult: {Function|String}
Default: null
If a closure action / action name is passed to the component, the action will receive the selected result.
handleResults: {Function|String}
Default: null
If a closure action / action name is passed to the component, the action will receive the results of the query.
loadingHandler: {Function|String}
Default: null
A closure action / action name that will receive a boolean which states if results are being loaded/fetched.
Roadmap
Future versions will allow you to persist results locally via localStorage
or some other storage method. For APIs with data that doesn't change often (e.g. addresses), this will allow for improved UX (search queries will appear to be instantaneous) and reduced load on the endpoint.
Installation
git clone
this repositorynpm install
bower install
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/.