Skip to content

An adapter to use ItemsJs based client-side search with an Algolia Instantsearch front-end.

License

Notifications You must be signed in to change notification settings

unplatform-io/instantsearch-itemsjs-adapter

Repository files navigation

Instantsearch-ItemsJS-adapter

Instantsearch-ItemsJS-adapter

License main

This library is an adapter that connects the search engine ItemsJS with the opensource tool Instantsearch (powered by Algolia) that lets you quickly build a search interface in your front-end application.

Table of Content

🔧 Installation
✏️ Usage
👀 Demo
📜 Features
🤝 Contribute

Installation

Use npm to install itemsjs-instantsearch-adapter.

npm install instantsearch-itemsjs-adapter

Instantsearch-ItemsJS-adapter does not create any UI component by itself.
To be able to create a search interface, you'll need to install Instantsearch as well.

Usage

import { createIndex, getSearchClient } from  "instantsearch-itemsjs-adapter";

const data = [{ "id":1,"title": "Iphone 7", "category":"Apple","price":109.95 },
{"id":1,"title": "Samsung notce 10","category":"Samsung","price":109.95 }]

const  options = {
	searchableFields: ["title"],
	query:  "",
	aggregations: {
		category: {
			title:  "category",
			size:  10,
			conjunction:  false,
		},
		price: {
			show_facet_stats: true
		},
	},
	sortings: {
		price_asc: {
			field:  "price",
			order:  "asc",
		},
		price_desc: {
			field:  "price",
			order:  "desc",
		},
	},
};

const index = createIndex(data, options);

const searchClient = getSearchClient(index);

options Options are from the ItemsJS API found here: ItemsJS

Demo

To see an implementation of this adapter go to unplatform-io/clientside-instantsearch-demo.

Features

Supported Instantsearch components

Component Explanation
Autocomplete Is not supported by ItemsJS
Breadcrumb ✔️
ClearRefinements ✔️
Configure ✔️
ConfigureRelatedItems Is not supported by ItemsJS
CurrentRefinements ✔️
DynamicWidgets Cannot be imported from react-instanstsearch-dom (version 6.12.1)
HierarchicalMenu ✔️
Highlight Is not supported by ItemsJS
Hits ✔️
HitsPerPage ✔️
Index Is not supported by ItemsJS
InfiniteHits ✔️
InstantSearch ✔️
Menu ✔️
MenuSelect ✔️
NumericMenu ✔️
Pagination ✔️
Panel ✔️
QueryRuleContext Is not supported by ItemsJS
QueryRuleCustomData Is not supported by ItemsJS
RangeInput ✔️
RangeSlider ✔️
RatingMenu ✔️
RefinementList ✔️
RelevantSort Is not supported by ItemsJS
ScrollTo ✔️
SearchBox ✔️
SearchState ✔️
Snippet Is not supported by ItemsJS
SortBy ✔️
StateResults ✔️
Stats ✔️
ToggleRefinement ✔️
VoiceSearch ✔️

✔️ Breadcrumb

Breadcrumb

The Breadcrumb widget allows a user to see where the current page is in relation to the facet’s hierarchy.

Parameter Explanation
attributes ✔️
separator ✔️
rootURL ✔️
transformItems ✔️
translations ✔️

✔️ ClearRefinements

ClearRefinements

The ClearRefinements widget allows a user to delete all applied filters.

Parameter Explanation
clearsQuery ✔️
translations ✔️
transformItems ✔️

✔️ Configure

Configure

The Configure widget allows a user to set fixed search parameters.

This widget can contain all Search Parameters, see this site for more information. ⚠️ The parameters are not tested, some may not work.

✔️ CurrentRefinements

CurrentRefinements

The CurrentRefinements widget allows a user to see wich filters are apllied.

Parameter Explanation
clearsQuery Do not set this to true, the interface will no longer work properly.
transformItems ✔️

✔️ HierarchicalMenu

HierarchicalMenu

The HierarchicalMenu widget allows a user to filter on a single value for an attribute.

Parameter Explanation
attributes ✔️
defaultRefinement ✔️
facetOrdering Is not supported by ItemsJS
limit ✔️
showMore ✔️
showMoreLimit ✔️
separator
rootPath ✔️
showParentLevel ✔️
transformItems ✔️
translations ✔️

✔️ Hits

Hits

The Hits widget allows a user to see the result of their search.

Parameter Explanation
hitComponent ✔️

✔️ HitsPerPage

HitsPerPage

The HitsPerPage widget allows a user to select how many hits wil appear on a page.

Parameter Explanation
items ✔️
defaultRefinement ✔️
transformItems ✔️

✔️ InfiniteHits

InfiniteHits

The InfiniteHits widget allows a user to see the result of their search.

Parameter Explanation
showPrevious ⚠️ Can only be used if URL Sync is implemented.
hitComponent ✔️
translations ✔️
cache ✔️

✔️ InstantSearch

InstantSearch

The InstantSearch widget allows a user to let all connected components (or widgets) interact with the searchState.

Parameter Explanation
indexName ✔️
searchClient ✔️
searchState ✔️
resultsState ✔️
createURL ✔️
onSearchStateChange ✔️
onSearchParameters ✔️
refresh ⚠️ There is no proof that this parameter works.
stalledSearchDelay ✔️

✔️ Menu

Menu

The Menu widget allows a user to filter on a single value for an attribute.

Parameter Explanation
attribute ✔️
defaultRefinement ✔️
facetOrdering Is not supported by ItemsJS
limit ✔️
showMore ✔️
showMoreLimit ✔️
searchable Is not supported by ItemsJS, ⚠️Warning: when set true UI will change but throws error when used
transformItems ✔️
translations ✔️

✔️ MenuSelect

MenuSelect

The MenuSelect widget allows a user to filter on a single value for an attribute.

Parameter Explanation
attribute ✔️
defaultRefinement ✔️
facetOrdering Is not supported by ItemsJS
limit ✔️
transformItems ✔️
translations ✔️

✔️ NumericMenu

NumericMenu

The NumericMenu widget allows a user to filter on a numeric field through the given ranges.

Parameter Explanation
attribute ✔️
items ✔️
defaultRefinement ✔️
transformItems ✔️
translations ✔️

⚠️ ItemsJS show_facet_stats needs to be true, for more information see Facet Stats.

✔️ Pagination

Pagination

The Pagination widget allows a user to change the current page.

Parameter Explanation
defaultRefinement ✔️
showFirst ✔️
showPrevious ✔️
showNext ✔️
showLast ✔️
padding ✔️
totalPages ✔️
translations ✔️

✔️ Panel

Panel

The Panel widget allows a user to wrap other widgets in a consistent design.

Parameter Explanation
className ✔️
header ✔️
footer ✔️

✔️ RangeInput

RangeInput

The rangeInput widget allows a user to filter on a numeric field using a minimum and/or maximum input.

Parameter Explanation
attribute ✔️
defaultRefinement ✔️
min ✔️
max ✔️
precision ✔️
translations ✔️

⚠️ ItemsJS show_facet_stats needs to be true, for more information see Facet Stats.

✔️ RangeSlider

RangeSlider

The RangeSlider widget allows a user to filter on a numeric field using a minimum and/or maximum input.

Parameter Explanation
attribute ✔️
defaultRefinement ✔️
min ✔️
max ✔️

⚠️ ItemsJS show_facet_stats needs to be true, for more information see Facet Stats.

✔️ RatingMenu

RatingMenu

The RatingMenu widget allows a user to filter on a numeric field by clicking on stars.

Parameter Explanation
attribute ✔️
defaultRefinement ✔️
min ✔️
max ✔️
translations ✔️

⚠️ ItemsJS show_facet_stats needs to be true, for more information see Facet Stats.

✔️ RefinementList

RefinementList

The RefinementList widget allows a user to filter on a facet/field.

Parameter Explanation
attribute ✔️
defaultRefinement ✔️
facetOrdering Is not supported by ItemsJS
operator ✔️Buildtime workaround available, see below
limit ✔️
showMore ✔️
showMoreLimit ✔️
searchable Is not supported by ItemsJS, ⚠️Warning: when set true UI will change but throws error when used
transformItems ✔️
translations ✔️

✔️Operator workaround:
Can be passed to ItemsJS buildtime (not available at runtime).
Set conjunction to true (OR operator) or false (AND operator).

aggregations: {
    category: {
      title: "category",
      conjunction: false,
    }
}

✔️ ScrollTo

ScrollTo

The ScrollTo widget allows a user to automatically scroll to an object when the searchState is adjusted.

Parameter Explanation
scrollOn ✔️

✔️ SearchBox

SearchBox

The SearchBox widget allows a user to search text based.

Parameter Explanation
defaultRefinement ⚠️ Text appears in the search box but the dataset is not searched.
autoFocus ✔️
searchAsYouType ✔️
showLoadingIndicator ✔️ There is no proof that this parameter works.
submit ✔️ There is no proof that this parameter works.
reset ✔️
loadingIndicator ✔️ There is no proof that this parameter works.
focusShortcuts ✔️
onSubmit ✔️
onReset ✔️
on* ✔️
translations ✔️

✔️ SearchState

SearchState

The SearchState widget allows a user to update their search parameters. When updated automaticly searched.

✔️ SortBy

Sortby

The sortBy widget allows a user to change the way hits are sorted.

Parameter Explanation
items ✔️
defaultRefinement ✔️
transformItems ✔️

With Instantsearch-ItemsJS-adapter you have to define the same key from your configuration sorting for the sortBy value. ItemsJS documentation for the configuration and searching can be found here ItemsJS configuration

sortings:  { 
	price_asc:  { field:  "price", order:  "asc",  }, 
	price_desc:  { field:  "price", order:  "desc", },  
},

<SortBy
	defaultRefinement=""
	items={[
		{ value:  "price_desc", label:  "High to low" },
		{ value:  "price_asc", label:  "Low to high" },
	]} 
/>

The usage of the sortBy widget differs from the one found in Aloglia's documentation. Instantsearch-ItemsJS-adapter does not make use of a replica indices

✔️ StateResults

StateResults

The StateResults widget allows a user to access the searchState and the searchResults of InstantSearch. For instance, this widget allows you to create results/no results or query/no query pages.

✔️ Stats

Stats

The Stats widget allows a user to displays the total number of matching hits and the time it took to get them (time spent in ItemsJS)

Parameter Explanation
translations ✔️

✔️ ToggleRefinement

ToggleRefinement

The ToggleRefinement widget allows a user to on/off filtering feature based on an attribute value

Parameter Explanation
attribute ✔️
label ✔️
value ✔️
defaultRefinement ✔️

✔️ VoiceSearch

VoiceSearch

The VoiceSearch widget allows a user to perform a voice-based query.

Parameter Explanation
searchAsYouSpeak ✔️
buttonTextComponent ✔️
statusComponent ✔️
translations ✔️

Facet Stats

For all nummeric fields show_facet_stats: true is required to calculate Instantsearch facet_stats and to avoid errors, it should be passed to ItemsJS, as shown below.

aggregations: {
    price: { show_facet_stats: true, }, 
},

<NumericMenu 
	attribute="price"
	items={[
              { label: "Less than 10", end: 10 },
              { label: "10 till 25", start: 10, end: 25 },
              { label: "25 till 50", start: 25, end: 50 },
              { label: "More than 50", start: 50 },
        ]} 
/>
<RangeInput attribute="price" />
<RangeSlider attribute="price" />
<RatingMenu attribute="price" />

Contribute

Help to this project is appreciated. If you want to help please use Jest and ESlint mentioned below, before creating a pull request.

To check functionalities run Jest tests, and if you make a new functionality also write some tests for this code.

npm run test

To keep the code clean run ESlint and resolve the errors when you're done programming.

npm run eslint

To automaticly resolve the errors run:

npm run eslint:fix