docs(refreshcache): add guide #732

marielaures · 2017-12-18T16:26:45Z

Summary

In the wake of the refresh cache feature (#619), this is a guide on how to refresh the cache with the description of the use case and an explanation of the two different approaches that can be used.

algobot · 2017-12-18T16:40:48Z

Deploy preview ready!

Built with commit bd57502

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

Haroenv

Really nice guide! some smaller issues and a question

Haroenv · 2017-12-18T17:31:29Z

docgen/src/guide/Handling_cache.md

+
+```jsx
+import React, { Component } from 'react';
+import { InstantSearch, SearchBox } from '../packages/react-instantsearch/dom';


... from 'react-instantsearch/dom'

Haroenv · 2017-12-18T17:31:48Z

docgen/src/guide/Handling_cache.md

+
+```jsx
+import React, { Component } from 'react';
+import { InstantSearch, SearchBox } from '../packages/react-instantsearch/dom';


react-instantsearch/dom

Haroenv · 2017-12-18T17:32:26Z

docgen/src/guide/Handling_cache.md

+
+See the example in this [story](https://community.algolia.com/react-instantsearch/storybook/?selectedKind=RefreshCache&selectedStory=with%20a%20refresh%20button&full=0&down=1&left=1&panelRight=1&downPanel=storybooks%2Fstorybook-addon-knobs). 
+
+ ## Refresh the cache periodically


This has a leading space

Yep, that space is here on purpose to get the heading format (see other guides)

Haroenv · 2017-12-18T17:35:02Z

docgen/src/guide/Handling_cache.md

+}
+```
+
+See the example in this [story](https://community.algolia.com/react-instantsearch/storybook/?selectedKind=RefreshCache&selectedStory=with%20setInterval&full=0&down=1&left=1&panelRight=1&downPanel=storybooks%2Fstorybook-addon-knobs).


Would be nice to have an example that explains

you do some action

index backend

waitTask

send some event to the frontend (maybe web sockets)

refresh

but it might be too long, because it has quite some setup with the sockets

Yes you are right it would be nice, but it's a bit harder to summarise. We point users to the right direction, they have the basics for using the update cache feature. IMO, how to receive the event for trigger the refresh is an implementation detail.

It might still be nice to mention that if they are waiting for an Algolia action, they'll need to use waitTask and send some event, otherwise the refreshing will be too early

vvo

Very well written guide, to the point. Congrats! Minor changes proposals, let us know

vvo · 2017-12-18T20:19:23Z

docgen/src/guide/Handling_cache.md

+
+While it is a very convenient feature, in some cases, it is useful to have the ability to clear the cache and make a new request to Algolia. For instance, when changes are made on some records on your index, you might want the frontend side of your application to be updated to reflect that change (in order to avoid displaying stale results retrieved from the cache).
+
+To do so, there is a prop on the `<InstantSearch>` component called `refresh` that, when set to true, clears the cache and triggers a new search.


proposal: true instead of true

vvo · 2017-12-18T20:22:19Z

docgen/src/guide/Handling_cache.md

+
+To do so, there is a prop on the `<InstantSearch>` component called `refresh` that, when set to true, clears the cache and triggers a new search.
+
+There are two different approaches to handle the cache:


Proposal:

There are two different use cases where you would want to discard the cache:

your application data is being updated by another process that you don't manage, for example a CRON job updates users inside Algolia. For this you might want to periodically refresh the cache of your app

you application data is being updated by the users of your app directly (for example, in a dashboard). In this use case you would want to refresh the cache base on some application state like the last modification of the user

wdyt?

I put this to better explains the scenarios.

vvo · 2017-12-18T20:23:17Z

docgen/src/guide/Handling_cache.md

+}
+```
+
+See the example in this [story](https://community.algolia.com/react-instantsearch/storybook/?selectedKind=RefreshCache&selectedStory=with%20a%20refresh%20button&full=0&down=1&left=1&panelRight=1&downPanel=storybooks%2Fstorybook-addon-knobs). 


See a live example in storybook

vvo · 2017-12-18T20:23:37Z

docgen/src/guide/Handling_cache.md

+}
+```
+
+See the example in this [story](https://community.algolia.com/react-instantsearch/storybook/?selectedKind=RefreshCache&selectedStory=with%20setInterval&full=0&down=1&left=1&panelRight=1&downPanel=storybooks%2Fstorybook-addon-knobs).


See a live example in storybook

samouss · 2017-12-18T16:47:51Z

docgen/src/guide/Handling_cache.md

@@ -0,0 +1,113 @@
+---
+title: Handling cache


Maybe use the title Refresh cache since I think a lots of people will search for this keyword.

Refreshing the cache

also sounds nice to me

samouss · 2017-12-18T16:55:12Z

docgen/src/guide/Handling_cache.md

+  refresh = () => {
+    this.setState(prevState => ({
+      refresh: !prevState.refresh,
+    }));


We can simplify the call. When we call refresh we always want to set the refresh to true.

this.setState({ refresh: true });

samouss · 2017-12-19T08:11:11Z

docgen/src/guide/Handling_cache.md

+}
+```
+
+See the example in this [story](https://community.algolia.com/react-instantsearch/storybook/?selectedKind=RefreshCache&selectedStory=with%20setInterval&full=0&down=1&left=1&panelRight=1&downPanel=storybooks%2Fstorybook-addon-knobs).


Yes you are right it would be nice, but it's a bit harder to summarise. We point users to the right direction, they have the basics for using the update cache feature. IMO, how to receive the event for trigger the refresh is an implementation detail.

samouss · 2017-12-19T08:13:45Z

docgen/src/guide/Handling_cache.md

+    setInterval(
+      () =>
+        this.setState({ refresh: true }, () =>
+          this.setState({ refresh: false })


It can be confusing for the user to use two different approach for reset the refresh property.

samouss · 2017-12-19T09:01:05Z

stories/RefreshCache.stories.js

+          count: prevState.count + 1,
+        })),
+      1000
+    );


We don't need to set two intervals, only one should be sufficient. Set an interval of 1000 and reset it when it reach the desired value. Then you can get rid of this component I think. Try to also use the same reset strategy as explained above.

samouss · 2017-12-19T09:02:19Z

stories/RefreshCache.stories.js

+    };
+  }
+
+  componentDidMount = () => {


Don't need to use a class property, the regular method should work componentDidMount() { ... }

samouss · 2017-12-19T20:33:26Z

docgen/src/guide/Refreshing_cache.md

+  }
+
+  refresh = () => {
+    this.setState({refresh: true});


Be careful with the code style. Prettier seems to nut run on the markdown in your editor. But you can still copy / paste the snippet inside the Prettier playground. Should be:

({ refresh: true })

You should be able to put the whole markdown in the playground, but we probably should have a lint-staged command that runs prettier on all staged files, WDYT?

samouss · 2017-12-19T20:34:48Z

docgen/src/guide/Refreshing_cache.md

+        >
+          Refresh cache
+        </button>
+        <CustomHits />


This variable doesn't exist in the snippet, use Hits instead of CustomHits. Don't forget to add the import.

samouss · 2017-12-19T20:38:28Z

docgen/src/guide/Refreshing_cache.md

+    };
+  }
+
+  componentDidMount = () => {


Prefer the usage of method instead of class property.

componentDidMount() { ... }

samouss · 2017-12-19T20:38:59Z

docgen/src/guide/Refreshing_cache.md

+
+   onSearchStateChange = () => {
+    this.setState({ refresh: false });
+  };


Add a space after this declaration.

samouss · 2017-12-19T20:39:22Z

docgen/src/guide/Refreshing_cache.md

+        onSearchStateChange={this.onSearchStateChange}
+      >
+        <SearchBox />
+        <CustomHits />


This variable doesn't exist in the snippet, use Hits instead of CustomHits. Don't forget to add the import.

samouss · 2017-12-19T20:40:14Z

docgen/src/guide/Refreshing_cache.md

+This method will ensure that the cache is cleared on a regular basis.
+You should use this approach if you cannot use a user action as a specific event to trigger the clearing of the cache.
+
+```jsx


Same comment as above, use Prettier for the all the snippet.

marielaures force-pushed the doc/handle-cache branch from 7f40928 to 252d5dc Compare December 18, 2017 16:41

Haroenv suggested changes Dec 18, 2017

View reviewed changes

vvo suggested changes Dec 18, 2017

View reviewed changes

samouss suggested changes Dec 19, 2017

View reviewed changes

marielaures force-pushed the doc/handle-cache branch 2 times, most recently from 61ba049 to e5e3b1f Compare December 19, 2017 17:35

samouss suggested changes Dec 19, 2017

View reviewed changes

Haroenv approved these changes Dec 19, 2017

View reviewed changes

marielaures and others added 6 commits December 20, 2017 09:07

doc(handleCache): add a story showing how to refresh cache periodically

387928b

doc(handleCache): add guide on how to handle cache

cb57b0e

doc(handleCache): integrate comment from PR

b225ce3

chore: prettier

4b9d1ab

docs: regular Hits component

82f3a76

fix(RefreshCache): add missing space

9e619a3

samouss force-pushed the doc/handle-cache branch from 51c0aad to 9e619a3 Compare December 20, 2017 08:07

samouss approved these changes Dec 20, 2017

View reviewed changes

fix: add missing trailing comma

bd57502

samouss merged commit 8b75957 into master Dec 20, 2017

samouss deleted the doc/handle-cache branch December 20, 2017 08:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(refreshcache): add guide #732

docs(refreshcache): add guide #732

marielaures commented Dec 18, 2017

algobot commented Dec 18, 2017 •

edited

Loading

Haroenv left a comment

Haroenv Dec 18, 2017

Haroenv Dec 18, 2017

Haroenv Dec 18, 2017

marielaures Dec 19, 2017

Haroenv Dec 18, 2017

samouss Dec 19, 2017

Haroenv Dec 19, 2017

vvo left a comment

vvo Dec 18, 2017

vvo Dec 18, 2017 •

edited by Haroenv

Loading

vvo Dec 18, 2017

vvo Dec 18, 2017

samouss Dec 18, 2017

Haroenv Dec 19, 2017

samouss Dec 18, 2017

samouss Dec 19, 2017

samouss Dec 19, 2017

samouss Dec 19, 2017

samouss Dec 19, 2017

samouss Dec 19, 2017

Haroenv Dec 19, 2017

samouss Dec 19, 2017

samouss Dec 19, 2017

samouss Dec 19, 2017

samouss Dec 19, 2017

samouss Dec 19, 2017


		See the example in this [story](https://community.algolia.com/react-instantsearch/storybook/?selectedKind=RefreshCache&selectedStory=with%20a%20refresh%20button&full=0&down=1&left=1&panelRight=1&downPanel=storybooks%2Fstorybook-addon-knobs).

		## Refresh the cache periodically


		While it is a very convenient feature, in some cases, it is useful to have the ability to clear the cache and make a new request to Algolia. For instance, when changes are made on some records on your index, you might want the frontend side of your application to be updated to reflect that change (in order to avoid displaying stale results retrieved from the cache).

		To do so, there is a prop on the `<InstantSearch>` component called `refresh` that, when set to true, clears the cache and triggers a new search.


		To do so, there is a prop on the `<InstantSearch>` component called `refresh` that, when set to true, clears the cache and triggers a new search.

		There are two different approaches to handle the cache:

docs(refreshcache): add guide #732

docs(refreshcache): add guide #732

Conversation

marielaures commented Dec 18, 2017

algobot commented Dec 18, 2017 • edited Loading

Haroenv 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

Choose a reason for hiding this comment

vvo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vvo Dec 18, 2017 • edited by Haroenv 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

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

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

algobot commented Dec 18, 2017 •

edited

Loading

vvo Dec 18, 2017 •

edited by Haroenv

Loading