It's extensive, clear, and, of course, searchable.
Sorry, there is no results for this query
Back in November 2015, we released InstantSearch.js v1 in order to give you an efficient way to build search UIs. We have received good feedback so far: 1600+ GitHub stars, 600+ upvotes on Product Hunt, and 1700+ live implementations and counting.
What we’ve found is that:
We’ve done our best to integrate what we’ve learned into InstantSearch.js v2, which we are releasing today. Here are some of the changes we’ve implemented.
Before getting down to nitty gritty details of this new API, let’s have a look at a practical use case.
On our blog we use a menu widget to let the user navigate into the categories. The behavior of this widget works perfectly here because of its unique properties:
This behavior is exactly the same as another well known UI element: the drop-down menu.
Some of you rightfully asked: “Can we render your menu widget as a drop-down element?”
The problem is that the HTML of both UI menu elements is completely different and can’t be expressed as template options. The two widgets’ HTML implementations are very different:
HTML rendering of the menu widget and a drop-down
Reflecting on that, we would have to either:
But adding more options does not make an API any good. This problem is actually deeper and can be phrased as:
“How can I precisely control the rendering of InstantSearch.js widgets?”
As we discussed during our release of react-instantsearch earlier this year, widgets are made up of two parts:
With the connectors API, we abstracted the search business logic into its own API, making it easier than ever for you to precisely control the rendering of any widget. The default IntantSearch.js widgets are implementations of their respective connectors.
The connector handles the business logic and exposes a simplified API to the rendering function (items, refine, widget parameters). In this case, it receives a function to change the currently selected value and the list of options to display. This makes the core logic of a widget easily reusable.
In v2, all the built-in widgets with a UI rendering now have their own connector. Because this is a significant change in the way the library is used, we needed to rethink the documentation:
In v1, the documentation layout was a single page with multiple columns. Visually it looked great but when the API grew, some issues started popping up:
After InstantSearch.js v1, we iterated a lot on our other documentation websites: places, JS Helper, React InstantSearch. With this knowledge and experience, we found that the best way of organizing documentation for libraries like ours is having multiple pages. For InstantSearch.js v2, we are introducing getting started and guides, and we are reorganizing the API reference into independent sections.
The getting started tutorial is the part that helps our new users most. Making it a prominent part of the navigation easily orients them. This is where we want to provide a good overview and real learning value.
Guides are also very important because we found that you can only do so much with an API. Guides provide a framework to users whose use cases may be too niche or advanced to use an obvious solution.
Finally, we kept and split up the API reference. Like we’ve done since InstantSearch.js v1, this part is completely built on top of the code documentation (jsdoc). We even go to the point of using it to create pseudocode examples to explain the API.
To learn more about what we think about documentation, read the blog post that we wrote about the user’s journey learning a library.
For the last part of this release, we also wanted to make sure that we are going to be able to continue to improve the library during this major version’s lifecycle. For this, we had to introduce a few breaking changes. All of them are documented in the migration guide.
Other notable changes:
With this version, we want to:
InstantSearch.js v2 is available and you can try it now:
As always with Algolia, your feedback is key to provide you the best tools. Encountering a bug? Open a GitHub issue, Want to showcase your awesome InstantSearch.js website? Post it to our forum and get expert feedback from our community.