docs(refining-hits): add a tutorial on how to refine within hits #258

Haroenv · 2017-08-14T16:00:36Z

this is a guide that finishes with https://codesandbox.io/embed/oY1klpZYB

fixes #244 and is obviously quite advanced

can be found in the deploy preview under guide/Refining_hits.html

this is a guide that finishes with https://codesandbox.io/embed/oY1klpZYB fixes #244 and is obviously quite advanced

Haroenv · 2017-08-14T16:00:46Z

docgen/src/guide/Refining_hits.md

+mainTitle: Guides
+layout: main.pug
+category: guide
+navWeight: # idk what to put here 🚨


what do we put here?

It's the number that allow you to positionate the guide in the sidebar. If you want it at the end, it should be bigger than the last one (not just by one to let other guide to be in between).

algobot · 2017-08-14T16:05:17Z

Deploy preview for react-instantsearch ready!

Built with commit b566919

https://deploy-preview-258--react-instantsearch.netlify.com

Haroenv · 2017-08-14T16:31:41Z

https://deploy-preview-258--react-instantsearch.netlify.com/guide/Refining_hits.html

rayrutjes

I made a few comments here and there.
Impressive stuff.

rayrutjes · 2017-08-14T19:37:44Z

docgen/src/guide/Refining_hits.md

+
+## Regular setup
+
+First, we'll set up a regular project wit create-react-app and react-instantsearch.


Wit => with

rayrutjes · 2017-08-14T19:41:38Z

docgen/src/guide/Refining_hits.md

+});
+```
+
+An index that already has these settings is the index for search on [Yarn](https://yarn.fyi), which is used in this guide. We will get started in `App.js` and set up a regular React InstantSearch setup:


In this guide we will use the search index we use on Yarn. It already has the mandatory attributesForFaceting configured.
We will get started in App.js and set up a regular React InstantSearch app:

rayrutjes · 2017-08-14T19:44:35Z

docgen/src/guide/Refining_hits.md

+export default Hit;
+```
+
+In this component we took the name, description and owner of a certain package, and render these as hits. To enable this as HitComponent, we will change the line in `App.js` that renders the `Hit` component:


Maybe quote HitComponent?
Weird tense switch here. I would stay with the present everywhere.

rayrutjes · 2017-08-14T19:45:49Z

docgen/src/guide/Refining_hits.md

+export default App;
+```
+
+We manually render the `hitComponent` as a function, because we want to add extra functions to the `Hit` component later. Now we will also set up two `RefinementList`s for `keywords` and `owner.name`. We do this in a container so that the difference is clear, but obviously you can change the rendering of this however you prefer:


Remove obviously

rayrutjes · 2017-08-14T19:48:00Z

docgen/src/guide/Refining_hits.md

+export default VirtualRefinementList;
+```
+
+Now this seems pretty useless, except that this component will get the correct props from its connector, each time something in its props change. The props we get from this connector are: `currentRefinement` and `defaultRefinement`. `defaultRefinement` is what we will manually set from within our Hit, `currentRefinement` is the current state of the search, relevant to that refinement, but maybe we should first implement it in our `App.js`: 


change => changes

I think the version that’s written here is the correct version

rayrutjes · 2017-08-14T19:49:11Z

docgen/src/guide/Refining_hits.md

+export default App;
+```
+
+We will change the state of `App` from within the `Hit` component later so that it will update the `defaultRefinement` of each respective `VirtualRefinementList`. To be able to handle with that cleanly, let's add a lifecycle hook in `VirtualRefinementList`:


To be able to achieve that in a clean way?

rayrutjes · 2017-08-14T19:50:19Z

docgen/src/guide/Refining_hits.md

+}
+```
+
+We compare the current refinement with the previous current refinement. If they aren't the same, then we will call a callback `onRefine` from our props with the current `attributeName` and with the new value. We do the same for the `defaultRefinement` so that the correct refinement is always chosen.


then we call the onRefine callback

rayrutjes · 2017-08-14T19:53:17Z

docgen/src/guide/Refining_hits.md

+}
+```
+
+This function works as follows: it has a `attributeName` and `value`, the value is what we want to add to the `VirtualRefinementList`, a string, for example `nodejs` or `react`. We will first check if our array for this attribute already contains that value. If it doesn't contain it, we simply add it to the array, if the array already contains the value we want, we remove it. Finally this value is set as the new state. Correspondingly, that change in state will trigger a change in `defaultRefinement` of the `VirtualRefinementList` for that attribute, and update the search interface. 


it has an attributeName and a value.

remove the simply

rayrutjes · 2017-08-14T19:54:04Z

docgen/src/guide/Refining_hits.md

+
+This function works as follows: it has a `attributeName` and `value`, the value is what we want to add to the `VirtualRefinementList`, a string, for example `nodejs` or `react`. We will first check if our array for this attribute already contains that value. If it doesn't contain it, we simply add it to the array, if the array already contains the value we want, we remove it. Finally this value is set as the new state. Correspondingly, that change in state will trigger a change in `defaultRefinement` of the `VirtualRefinementList` for that attribute, and update the search interface. 
+
+But we still need to call this function. What we do is add `this.refine` as a prop to the `Hit` component, and call it there when needed. The inside of the `Hit` component now looks like this: 


The Hit component implementation now looks like this:

mthuret · 2017-08-16T12:36:39Z

If someone only wants the list of tags on Hits without the other RefinementList does it simplify things?

mthuret

Awesome work @Haroenv, that's a great use case added to RIS :)

mthuret · 2017-08-16T12:31:47Z

docgen/src/guide/Refining_hits.md

+
+## Introduction
+
+In some interfaces, you want to have buttons _inside_ your Hits that will change the refinement of the current search, rather than as standalone components. Since we can't replicate this pattern with widgets, we will need to go with Refinementlists that don't render anything. Please note that this is an advanced tutorial and requires moderate knowledge of how React and React InstantSearch work. Our final result will look something like this, let's get started!


I think we should start directly by evoking the "List of tags" use case that speaks easily to somebody.

mthuret · 2017-08-16T12:33:10Z

docgen/src/guide/Refining_hits.md

+
+## Introduction
+
+In some interfaces, you want to have buttons _inside_ your Hits that will change the refinement of the current search, rather than as standalone components. Since we can't replicate this pattern with widgets, we will need to go with Refinementlists that don't render anything. Please note that this is an advanced tutorial and requires moderate knowledge of how React and React InstantSearch work. Our final result will look something like this, let's get started!


Refinementlists => RefinementLists

Mention Virtual Widgets and link to the guide

In the end we should have a clear prerequisites list.

mthuret · 2017-08-16T12:34:41Z

docgen/src/guide/Refining_hits.md

+$ yarn add react-instantsearch # or npm install --save react-instantsearch
+```
+
+The index that we will use in this example needs to be set up with: 


This part is confusing. The code sample uses an index that is already configured. If the user wants to use his own he will not have the same attribute name. I guess this should be rephrase a bit.

mthuret · 2017-08-16T12:35:33Z

docgen/src/guide/Refining_hits.md

+
+## Adding virtual RefinementLists
+
+A "virtual" RefinementList is a RefinementList, just like the ones that are using the regular widgets, but with the exception that they won't render anything. We will make a virtual RefinementList here that will take `defaultRefinement` into account when rendering. We will make a `VirtualRefinementList` component, which uses a `connectRefinementList`: 


I believe we should introduce this paragraph by explaining why we need virtual widgets in the first place

Haroenv · 2017-08-17T11:02:31Z

You mean just keywords and not owner.name? Yes, that’s a bit more simple, but was pretty limiting. I like this solution better, since it’s simpler in the end. In the Yarn website it’s still using the “there can only be one attribute” way of doing things, and will probably change that to what I described here.

Showing the real refinement list doesn’t make it more or less complex

mthuret · 2017-08-18T09:15:50Z

I was talking about this: "Showing the real refinement list doesn’t make it more or less complex".

Haroenv · 2017-08-18T09:48:08Z

Only difference is when you show the real refinementList that there are some errors in the console

mthuret · 2017-08-28T17:00:38Z

Additional notes: I played with it a bit, it works like a charm except that it produces 3-4 query per selection. Do we have a way to optimize this @Haroenv?

Haroenv · 2017-09-06T12:53:47Z

Hmm, should look at that issue @mthuret, thanks for noticing! I wonder what the cause would be, since it should just be another refinementList

Haroenv · 2017-09-19T17:26:53Z

It's the virtualRefinementList that causes the queries, the actual widgets being there doesn't matter there has no effect

mthuret · 2017-09-20T08:29:51Z

@Haroenv did you had the chance to understand why? Can we fix it? I'm not comfortable with shipping a guide that does all those extra queries and I'd rather try to find a solution that is cleaner. It might involved dedicated dev if nothing possible using React capabilities.

Haroenv · 2017-09-20T09:21:09Z

No, I didn't find the actual reason yet, it doesn't seem easy to find out what the cause of the queries are. See also #355

vvo · 2017-09-26T09:34:30Z

Quick note, is the status on this PR pending while we find reasons for #355?

Haroenv · 2017-09-26T09:50:40Z

yep, this PR is blocked by #355

vvo · 2017-10-16T15:06:41Z

@Haroenv Any way we can move forward with this PR? Is there anything we can do to help? Maybe the behaviour has changed now

Haroenv · 2017-10-16T21:01:56Z

Interesting, with newest RIS and React they show up twice, still multiple queries per refinement too...

https://codesandbox.io/s/oY1klpZYB

Haroenv · 2017-12-06T09:50:50Z

Whoa, there's no longer a duplicate query done, will look at the comments, then it's mergeable

vvo · 2017-12-07T10:36:42Z

Whoa, there's no longer a duplicate query done, will look at the comments, then it's mergeable

How come? :D

Haroenv · 2018-01-10T18:26:59Z

This is ready for review: https://deploy-preview-258--react-instantsearch.netlify.com/react-instantsearch/guide/refining_hits

The last section still needs to be verified based on #830

…ems for deduplication (#830) **Summary** The currentRefinemements widget (and connector) will give exactly the same data as the widgets which are present in the layout. As seen in #258, when there are two refinements with the same attribute, this will give those items the same `key` and render with warnings. **Result** 1. Give access to `index` and `id` (`${attributeName}`, `query`, ...) to `tranformItems` so users can deduplicate themselves 2. test how the deduplication can be done

vvo · 2018-01-16T09:58:25Z

Do we need anything else on this PR to move?

Haroenv · 2018-01-16T10:02:35Z

needs another review, implementation of that last deduplication in the CodeSandbox and a release of that

samouss · 2018-01-16T10:05:05Z

I will review it today or tomorrow.

samouss · 2018-01-19T12:27:32Z

docgen/src/guide/Refining_hits.md

+
+      // if it's already refined, remove it from the refinements
+      const newValue = refinements[attributeName].slice();
+      newValue.splice(index, 1);


You can use a filter instead of a splice but it's matter of preference :)

samouss

LGTM, but we need to test the last part after the release.

samouss · 2018-01-19T12:54:25Z

Note that for this kind of behaviour it might be interesting to have something like a "controlled" widgets. For example by providing the currentRefinement to the widget. The prop became the source of truth instead of the searchState. In that case it will allow us to get rid of the part with the double check on defaultRefinement + currentRefinement since the "real" value will always be the currentRefinement.

In React the input element works a bit like that:

without a value the element is uncontrolled but you can still provide a defaultValue that will be used only for the first render (this is our behaviour)
with a value the element is controlled and you are responsible for all changes

Haroenv · 2018-01-19T13:31:09Z

Will that still allow changes from “upstream”?

samouss · 2018-01-24T18:29:33Z

Sorry I didn’t see the question. What do you mean by that?

The version with the update on CurrentRefinements has been released so we can test the de duplication part.

Haroenv · 2018-01-24T18:44:54Z

docgen/src/guide/Refining_hits.md

+  render() {
+    return (
+      // the rest of the app
+      <CurrentRefinements transformData={deleteDuplicates} />


should be transformItems

+ it doesn't work with more than 1 duplicate 🤔

Haroenv · 2018-01-24T18:59:22Z

docgen/src/guide/Refining_hits.md

+
+```jsx
+// ...
+const deleteDuplicates = items =>


this is wrong, should be:

export const deleteDuplicates = (items) => items .map(item => { // make a temporary key for deduplication item.__dedupe = `${item.index}.${item.id}`; return item; }) .filter( (obj, pos, arr) => arr.map(item => item.__dedupe).indexOf(obj.__dedupe) === pos ) .map(item => { // delete it afterwards delete item.__dedupe; return item; });

export const deleteDuplicates = (items) => items .filter( (obj, pos, arr) => arr.map(item => `${item.index}.${item.id}`).indexOf(`${obj.index}.${obj.id}`) === pos )

two less iterations, but probably less performant due to string creation in hot loop (still O(n!))

Since the array is pretty small (less than 50 elements most of the time) I think the more understandable is the best 🙂

samouss · 2018-02-13T14:39:57Z

@Haroenv I still have multiple queries but they won't be inevitable at some point since we play with the defaultRefinement. But for example when you click on the CurrentRefinements it triggers 4 requests. Maybe we should try remove some of them before merging this? I'm not sure that with the current state of the lib we could reduce the number of requests.

samouss · 2018-12-10T09:06:12Z

We can't merge it right away because of the number of requests that are triggered. We keep the branch until we have a proper solution for the request issue.

Haroenv added 2 commits August 14, 2017 16:59

docs(refining-hits): add a tutorial on how to refine within hits

f8a4db4

this is a guide that finishes with https://codesandbox.io/embed/oY1klpZYB fixes #244 and is obviously quite advanced

finish the article

965eb2d

Haroenv requested review from mthuret and marielaures August 14, 2017 16:00

Haroenv commented Aug 14, 2017

View reviewed changes

rayrutjes reviewed Aug 14, 2017

View reviewed changes

Updates by @rayrutjes

4b73866

mthuret previously requested changes Aug 16, 2017

View reviewed changes

Merge branch 'master' into docs/refine-from-hits

b12f1a9

Merge branch 'master' into docs/refine-from-hits

9f22cf9

vvo added the DO NOT MERGE - Only for review label Sep 26, 2017

Merge branch 'master' into docs/refine-from-hits

f73eb77

Merge branch 'master' into docs/refine-from-hits

d90e604

Haroenv and others added 2 commits January 12, 2018 10:01

Merge branch 'master' into docs/refine-from-hits

c15b0ee

chore: use delete because it's a _lot_ faster

7e7b515

Haroenv added 2 commits January 16, 2018 11:02

Merge branch 'master' into docs/refine-from-hits

41275a4

quotes

942c80e

Merge branch 'master' into docs/refine-from-hits

a8834e6

samouss reviewed Jan 19, 2018

View reviewed changes

Merge branch 'master' into docs/refine-from-hits

d70977f

Merge branch 'master' into docs/refine-from-hits

218567c

Haroenv commented Jan 24, 2018

View reviewed changes

Haroenv added 2 commits January 29, 2018 14:51

Update Refining_hits.md

f7c9bc6

Update Refining_hits.md

7fac044

Haroenv added Documentation: Guide and removed DO NOT MERGE - Only for review labels Jan 29, 2018

Merge branch 'master' into docs/refine-from-hits

ad755dc

Haroenv added 2 commits February 13, 2018 15:44

Merge branch 'master' into docs/refine-from-hits

76f5c56

Merge branch 'master' into docs/refine-from-hits

b566919

samouss closed this Dec 10, 2018

Haroenv deleted the docs/refine-from-hits branch November 20, 2019 17:01


		## Regular setup

		First, we'll set up a regular project wit create-react-app and react-instantsearch.


		This function works as follows: it has a `attributeName` and `value`, the value is what we want to add to the `VirtualRefinementList`, a string, for example `nodejs` or `react`. We will first check if our array for this attribute already contains that value. If it doesn't contain it, we simply add it to the array, if the array already contains the value we want, we remove it. Finally this value is set as the new state. Correspondingly, that change in state will trigger a change in `defaultRefinement` of the `VirtualRefinementList` for that attribute, and update the search interface.

		But we still need to call this function. What we do is add `this.refine` as a prop to the `Hit` component, and call it there when needed. The inside of the `Hit` component now looks like this:


		## Introduction

		In some interfaces, you want to have buttons _inside_ your Hits that will change the refinement of the current search, rather than as standalone components. Since we can't replicate this pattern with widgets, we will need to go with Refinementlists that don't render anything. Please note that this is an advanced tutorial and requires moderate knowledge of how React and React InstantSearch work. Our final result will look something like this, let's get started!


		## Adding virtual RefinementLists

		A "virtual" RefinementList is a RefinementList, just like the ones that are using the regular widgets, but with the exception that they won't render anything. We will make a virtual RefinementList here that will take `defaultRefinement` into account when rendering. We will make a `VirtualRefinementList` component, which uses a `connectRefinementList`:

docs(refining-hits): add a tutorial on how to refine within hits #258

docs(refining-hits): add a tutorial on how to refine within hits #258

Conversation

Haroenv commented Aug 14, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

algobot commented Aug 14, 2017 • edited Loading

Haroenv commented Aug 14, 2017

rayrutjes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rayrutjes Aug 14, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mthuret commented Aug 16, 2017

mthuret left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Haroenv commented Aug 17, 2017

mthuret commented Aug 18, 2017

Haroenv commented Aug 18, 2017

mthuret commented Aug 28, 2017

Haroenv commented Sep 6, 2017

Haroenv commented Sep 19, 2017

mthuret commented Sep 20, 2017

Haroenv commented Sep 20, 2017

vvo commented Sep 26, 2017

Haroenv commented Sep 26, 2017

vvo commented Oct 16, 2017

Haroenv commented Oct 16, 2017

Haroenv commented Dec 6, 2017

vvo commented Dec 7, 2017

Haroenv commented Jan 10, 2018

vvo commented Jan 16, 2018

Haroenv commented Jan 16, 2018

samouss commented Jan 16, 2018

samouss Jan 19, 2018 • edited Loading

Choose a reason for hiding this comment

samouss left a comment

Choose a reason for hiding this comment

samouss commented Jan 19, 2018

Haroenv commented Jan 19, 2018

samouss commented Jan 24, 2018

Haroenv Jan 24, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Haroenv Jan 25, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samouss commented Feb 13, 2018

samouss commented Dec 10, 2018

algobot commented Aug 14, 2017 •

edited

Loading

rayrutjes Aug 14, 2017 •

edited

Loading

samouss Jan 19, 2018 •

edited

Loading

Haroenv Jan 24, 2018 •

edited

Loading

Haroenv Jan 25, 2018 •

edited

Loading