ember-search-flow
v3.0.1
Published
Multi-faceted search for ember.
Downloads
267
Maintainers
Readme
Ember-search-flow
This is a dependency free multi-faceted search based on many of the "visual search" packages out there designed for ember. See the demo at https://alechirsch.github.io/ember-search-flow/
Installation
ember install ember-search-flow
Usage
Once installed, include the component in any template
{{search-flow
parameters=parameters
query=query
onQueryUpdated=(action 'onQueryUpdated')
onValueUpdated=(action 'onValueUpdated')
}}
Options | Default Value | Description
---|---|---
searchLabel
| 'Add Filter'
| The text displayed next to the add filter button.
clearLabel
| 'Clear Filters'
| The text displayed next to the clear all filters button. By default, this button will not be displayed until two or more filters are added.
maxFilters
| null
| The maximum number of filters allowed to be added by the user. This will not block the number of filters manually passed in through the query object. Any non-number value will be treated as infinite.
Query
The query is an object of filters that you can use in an ember store query This is the output of the component, you can also use it to initialize the filters for the component. For example, if you want to filter a list of users by the name "Bob" and age of "25", the query object will look like this
{
name: "Bob",
age: 25
}
A query for filtering by "Bob" or "Bill" AND age 25:
{
name: ["Bob", "Bill"],
age: 25
}
There is also an option to query on a partial string using the "contains" key in the query. A query for filterting all on names that contain the letter "b":
{
contains: {
name: "b"
}
}
Parameters
Parameters is an array of objects that define what filters can be added to the query. Each object in the array is defined with the following options
| Key | Required | Description | |-------|----------|-------------| | name | yes | The key of the filter in the query | | title | yes | The text to be displayed for the name of filter. | | placeholder | no | The displayed string for a parameter when no value is typed into the input box. | | allowMultiple | no | Default is true. Setting to false will allow only one filter of this parameter in the query. | | contains | no | Default is false. This enables a filter to use the 'contains' key in the query. | | options | no | This is an array of strings that represents the available options for the parameter. || options | no | This is an array of strings that represents the available options for the parameter. | | remoteOptions | no | Default is false. If set to true, the options are remotely obtained and the onValueUpdated action will be called whenever the value of an input changes. Refer to the section about the onValueUpdated action. | | suggested | no | Default is false. Setting to true will place the filter into the suggested filters list. | | sort | no | Default is true. Setting to false will not auto sort the options list. The sort is alphabetical. |
Here is an example of a parameter that does not use remote options and where a user can only input one of:
{
name: 'status',
title: 'Status',
options: ['New', 'Open', 'Pending', 'Closed'],
placeholder: 'Enter status',
allowMultiple: false
}
onValueUpdated
This action is called only if remoteOptions is set to true. Whenever a user changes the value of an input box, this action is called with two parameters:
- value The value that was entered into the input box
- parameter The parameter that was defined in the parameters array.
This action should set the 'options' on the parameter to an array of string that are the available options.
onValueUpdated(value, parameter){
// do remote call
let options = // results from remote call
Ember.set(parameter, 'options', options);
}
Optionally, you can configure your Ember application to have Search Flow set a timeout prior to querying your resource for options to show. In your Ember environment file, export a Search Flow configuration like the following:
'ember-search-flow': {
optionsTimeout: 1000
}
This will make Search Flow wait one second after the user finishes typing before sending out requests for options to show. If you choose to use this timeout configuration you must change the return value of your onValueUpdated function to be a Promise of the array of options.
onQueryUpdated
This action is called each time ember-search-flow makes a new query from a newly selected key-value pair. Pointing this attribute to an action in a route or component enables you to listen and define behavior when filters are created or deleted.
onQueryUpdated(query){
this.set('routeFilter', query);
//refresh the route, newFilter is used by a this.store.query call to make JSONAPI call to a resource server
this.refresh();
}
Development
git clone https://github.com/alechirsch/ember-search-flow.git
cd ember-search-flow
npm link
cd ../dummy-app
npm link ember-search-flow
npm install
bower install
Running
ember serve
- Visit your app at http://localhost:5000.
For more information on using ember-cli, visit http://ember-cli.com/.