Coming from V1 (or js client v2)? Read the migration guide to the new version of the Helper.
algoliasearch-helper-js
This module is the companion of the algolia/algoliasearch-client-js. It helps you keep
track of the search parameters and provides a higher level API.
This is the library you will need to easily build a good search UX like our instant search demo.
See the helper in action
Features
- Search parameters management
- Facets exclusions
- Pagination
- Disjunctive faceting (search on two or more values of the same facet)
Example
A small example that uses Browserify to manage modules.
var algoliasearch = require('algoliasearch');
var algoliasearchHelper = require('algoliasearch-helper');
var client = algoliasearch('appId', 'apiKey');
var helper = algoliasearchHelper(client, 'indexName', {
facets: ['mainCharacterFirstName', 'year'],
disjunctiveFacets: ['director']
});
helper.on('result', function(data){
console.log(data.hits);
});
helper.addDisjunctiveRefine('director', 'Clint Eastword');
helper.addDisjunctiveRefine('director', 'Sofia Coppola');
helper.addNumericRefinement('year', '=', 2003);
helper.search();
Helper cheatsheet
There is also a complete JSDoc
Add the helper in your project
Regular <script>
tag
Use our jsDelivr build:
<script src="//cdn.jsdelivr.net/algoliasearch.helper/2/algoliasearch.helper.min.js"></script>
With NPM
npm install algoliasearch-helper
With bower
bower install algoliasearch-helper
Init the helper
var helper = algoliasearchHelper(client, 'indexName');
Helper lifecycle
-
modify the parameters of the search (usually through user interactions)
helper.setQuery('iphone').addRefine('category', 'phone')
-
trigger the search (after all the modification have been applied)
helper.search()
-
read the results (with the event "result" handler) and update the UI with the results
helper.on('result', function(results) { updateUI(results); });
-
go back to 1
Objects
AlgoliasearchHelper: the helper. Keeps the state of the search, makes the queries and calls the handlers when an event happen.
SearchParameters: the object representing the state of the search. The current state is stored in helperInstance.state
.
SearchResults: the object in which the Algolia answers are transformed into. This object is passed to the result event handler.
An example of SearchResults in JSON is available at the end of this readme
Search
The search is triggered by the search()
method.
It takes all the previous modifications to the search and uses them to create the queries to Algolia. The search parameters are immutable.
Example:
var helper = algoliasearchHelper(client, indexName);
helper.on('result', function(content) {
console.log(content);
});
helper.search();
helper.setQuery('landscape').search();
helper.addTag('photo').search();
Events
The helper is an Event Emitter.
result
: get notified when new results are received. The handler function will receive
two objects (SearchResults
and SearchParameters
).
error
: get notified when errors are received from the API.
change
: get notified when a property has changed in the helper
Listen to the result
event
helper.on('result', updateTheResults);
Listen to a result
event once
helper.once('result', updateTheResults);
Remove all result
listeners
helper.removeListener('result');
Query
Do a search with the query "fruit"
helper.setQuery('fruit').search();
Filtering results
Facets are filters to retrieve a subset of an index having a specific value for a given attribute. First you need to define which attribute will be used as a facet in the dashboard: https://www.algolia.com/explorer#?tab=display
"AND" facets
Facet definition
var helper = algoliasearchHelper(client, indexName, {
facets: ['ANDFacet']
});
Add a facet filter
helper.addRefine('ANDFacet', 'valueOfANDFacet').search();
Remove a facet filter
helper.removeRefine('ANDFacet', 'valueOfANDFacet').search();
"OR" facets
Facet definition
var helper = algoliasearchHelper(client, indexName, {
disjunctiveFacets: ['ORFacet']
});
Add a facet filter
helper.addDisjunctiveRefine('ORFacet', 'valueOfORFacet').search();
Remove a facet filter
helper.removeDisjunctiveRefine('ORFacet', 'valueOfORFacet').search();
Negative facets
filter so that we do NOT get a given category
Facet definition (same as "AND" facet)
var helper = algoliasearchHelper(client, indexName, {
facets: ['ANDFacet']
}).search();
Exclude a value for a facet
helper.addExclude('ANDFacet', 'valueOfANDFacetToExclude');
Remove an exclude from the list of excluded values
helper.removeExclude('ANDFacet', 'valueOfANDFacetToExclude');
Numeric facets
Filter over numeric attributes with math operations like =
, >
, <
, >=
, <=
. Can be used for numbers and dates (if converted to timestamp)
Facet definition
var helper = algoliasearchHelper(client, indexName, {
disjunctiveFacets: ['numericFacet']
});
Add a numeric refinement
helper.addNumericRefinement('numericFacet', '=', '3').search();
Remove a numeric refinement
helper.removeNumericRefinemetn('numericFacet', '=', '3').search();
Hierarchical facets
Hierarchical facets are useful to build such navigation menus:
| products
> fruits
> citrus
| strawberries
| peaches
| apples
Here, we refined the search this way:
- click on fruits
- click on citrus
To build such menu, you need to use hierarchical faceting:
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1']
}]
});
Given your objects looks like this:
{
"objectID": "123",
"name": "orange",
"categories": {
"lvl0": "fruits",
"lvl1": "fruits > citrus"
}
}
And you refine products
:
helper.toggleRefine('products', 'fruits > citrus');
You will get a hierarchical presentation of your facet values: a navigation menu
of your facet values.
helper.on('result', function(data){
console.log(data.hierarchicalFacets[0]);
});
To ease navigation, we always:
- provide the root level categories
- provide the current refinement sub categories (
fruits > citrus > *
: n + 1) - provide the parent refinement (
fruits > citrus
=> fruits
: n -1) categories - refine the search using the current hierarchical refinement
Specifying another separator
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1'],
separator: '|'
}]
});
helper.toggleRefine('products', 'fruits|citrus');
Would mean that your objects look like so:
{
"objectID": "123",
"name": "orange",
"categories": {
"lvl0": "fruits",
"lvl1": "fruits|citrus"
}
}
Specifying a different sort order for values
The default sort for the hierarchical facet view is: isRefined:desc (first show refined), name:asc (then sort by name)
.
You can specify a different sort order by using:
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1'],
sortBy: ['count:desc', 'name:asc']
}]
});
The available sort tokens are:
Asking for the current breadcrumb
var helper = algoliasearchHelper(client, indexName, {
hierarchicalFacets: [{
name: 'products',
attributes: ['categories.lvl0', 'categories.lvl1'],
separator: '|'
}]
});
helper.toggleRefine('products', 'fruits|citrus');
var breadcrumb = helper.getHierarchicalFacetBreadcrumb('products');
console.log(breadcrumb);
console.log(breadcrumb.join(' | '));
Clearing filters
Clear all the refinements for all the refined attributes
helper.clearRefinements().search();
Clear all the refinements for a specific attribute
helper.clearRefinements('ANDFacet').search();
[ADVANCED] Clear only the exclusions on the "ANDFacet" attribute
helper.clearRefinements(function(value, attribute, type) {
return type === 'exclude' && attribute === 'ANDFacet';
}).search();
Tags
Tags are an easy way to do filtering. They are based on a special attribute in the records named _tags
, which can be a single string value or an array of strings.
Add a tag filter for the value "landscape"
helper.addTag('landscape').search();
Remove a tag filter for the value "landscape"
helper.removeTag('landscape').search();
Clear all the tags filters
helper.clearTags().search();
Get the current page
helper.getCurrentPage();
Change page
helper.setCurrentPage(3).search();
Index
Index can be changed. The common use case is when you have several slaves with different sort order (sort by relevance, price or any other attribute).
Change the current index
helper.setIndex('index_orderByPrice').search();
Get the current index
var currentIndex = helper.state.index;
Query parameters
There are lots of other parameters you can set.
Set a parameter at the initialization of the helper
var helper = algoliasearchHelper(client, indexName, {
hitsPerPage: 50
});
Set a parameter later
helper.setQueryParameter('hitsPerPage', 20).search();
List of parameters that can be set
Results format
Here is an example of a result object you get with the result
event.
{
"hitsPerPage": 10,
"processingTimeMS": 2,
"facets": [
{
"name": "type",
"data": {
"HardGood": 6627,
"BlackTie": 550,
"Music": 665,
"Software": 131,
"Game": 456,
"Movie": 1571
},
"exhaustive": false
},
{
"exhaustive": false,
"data": {
"Free shipping": 5507
},
"name": "shipping"
}
],
"hits": [
{
"thumbnailImage": "http://img.bbystatic.com/BestBuy_US/images/products/1688/1688832_54x108_s.gif",
"_highlightResult": {
"shortDescription": {
"matchLevel": "none",
"value": "Safeguard your PC, Mac, Android and iOS devices with comprehensive Internet protection",
"matchedWords": []
},
"category": {
"matchLevel": "none",
"value": "Computer Security Software",
"matchedWords": []
},
"manufacturer": {
"matchedWords": [],
"value": "Webroot",
"matchLevel": "none"
},
"name": {
"value": "Webroot SecureAnywhere Internet Security (3-Device) (1-Year Subscription) - Mac/Windows",
"matchedWords": [],
"matchLevel": "none"
}
},
"image": "http://img.bbystatic.com/BestBuy_US/images/products/1688/1688832_105x210_sc.jpg",
"shipping": "Free shipping",
"bestSellingRank": 4,
"shortDescription": "Safeguard your PC, Mac, Android and iOS devices with comprehensive Internet protection",
"url": "http://www.bestbuy.com/site/webroot-secureanywhere-internet-security-3-devi…d=1219060687969&skuId=1688832&cmp=RMX&ky=2d3GfEmNIzjA0vkzveHdZEBgpPCyMnLTJ",
"name": "Webroot SecureAnywhere Internet Security (3-Device) (1-Year Subscription) - Mac/Windows",
"category": "Computer Security Software",
"salePrice_range": "1 - 50",
"objectID": "1688832",
"type": "Software",
"customerReviewCount": 5980,
"salePrice": 49.99,
"manufacturer": "Webroot"
},
....
],
"nbHits": 10000,
"disjunctiveFacets": [
{
"exhaustive": false,
"data": {
"5": 183,
"12": 112,
"7": 149,
...
},
"name": "customerReviewCount",
"stats": {
"max": 7461,
"avg": 157.939,
"min": 1
}
},
{
"data": {
"Printer Ink": 142,
"Wireless Speakers": 60,
"Point & Shoot Cameras": 48,
...
},
"name": "category",
"exhaustive": false
},
{
"exhaustive": false,
"data": {
"> 5000": 2,
"1 - 50": 6524,
"501 - 2000": 566,
"201 - 500": 1501,
"101 - 200": 1360,
"2001 - 5000": 47
},
"name": "salePrice_range"
},
{
"data": {
"Dynex™": 202,
"Insignia™": 230,
"PNY": 72,
...
},
"name": "manufacturer",
"exhaustive": false
}
],
"query": "",
"nbPages": 100,
"page": 0,
"index": "bestbuy"
}