Add guide "Create a Calendar Widget" #2687

francoischalifour · 2018-01-31T16:13:15Z

~~⚠️ Waiting for #2686 and algolia/create-instantsearch-app#8 to be merged.~~ DONE ✅

This PR is the result of the app and the guide: "Create a Calendar Widget".

I'm looking for feedback on both the app and the guide 🙌

algobot · 2018-01-31T16:21:01Z

Deploy preview for algolia-instantsearch ready!

Built with commit 1f6f89b

https://deploy-preview-2687--algolia-instantsearch.netlify.com

Haroenv

This is probably the best guide I've read! Very clear and beginner-friendly. I left some comments on smaller things, nothing too blocking

Haroenv · 2018-02-01T10:00:45Z

docgen/src/guides/calendar-widget.md

+* `location`: the venue of the concert
+* `date`: the date of the event we will refine the results with
+
+Both `name` and `location` will be added to the [searchable attributes](https://www.algolia.com/doc/guides/ranking/searchable-attributes/) in the Algolia dashboard so that the user can filter events on their name *and* their location.


no need for italic and IMO

Haroenv · 2018-02-01T10:01:17Z

docgen/src/guides/calendar-widget.md

+
+If you're using [npm](https://www.npmjs.com/):
+
+```console


console is not recognised, and is showing it very faint, try sh, bash or nothing

Haroenv · 2018-02-01T10:02:00Z

docgen/src/guides/calendar-widget.md

+If you're using [npm](https://www.npmjs.com/):
+
+```console
+npm install -g create-instantsearch-app


npx create-instantsearch-app [name-of-your-new-app]

I feel so old 👴 what is npx?

It's something npm 5 has, doing install globally and execute the binary, like yarn create

Haroenv · 2018-02-01T10:03:22Z

docgen/src/guides/calendar-widget.md

+yarn create instantsearch-app [name-of-your-new-app]
+```
+
+The command-line tool will ask for your credentials:


I'm missing here where the dataset is, maybe list the credentials here, will be clearer, and we show them in the example anyway

You're right, I should expose them. Should I make the JSON dataset downloadable?

Yes the JSON dataset should be provided.

both the json and the credentials should be given IMO, you can put the JSON in https://github.com/algolia/datasets

I'm not convinced the dataset is good enough to be officially exposed though. I might work a bit more on that beforehand!

Haroenv · 2018-02-01T10:05:01Z

docgen/src/guides/calendar-widget.md

+The default `item` template from the `hits` widget provided by `create-instantsearch-app` is great, but we're going to enhance it to display the relevant information of our dataset.
+
+```javascript
+search.addWidget(


this is runnable for some reason, but it doesn't work with the demo instant_search index; @bobylito can we make that configurable in the guide metadata 🤔 ?

Oh :/ It's because we do:

if (exampleContent.indexOf("search.addWidget") === 0) { initWidgetExample(codeSample, index); }

in the runnable code JS :/

It would be nice if the index would be configurable based on the page metadata, do you think that's possible @bobylito ?

Working on it!

PR sent #2690

Haroenv · 2018-02-01T10:06:47Z

docgen/src/guides/calendar-widget.md

+);
+```
+
+We use the function syntax for the `item` template because we want to convert the numeric timestamp from our dataset to a JavaScript date on the fly.


on the fly. + Be careful here with user-generated data, you can use existing libraries to prevent XSS, + or use a template and `transformData` instead.

(we don't currently have a guide on XSS I think, otherwise it should be linked

Haroenv · 2018-02-01T10:09:23Z

docgen/src/guides/calendar-widget.md

+      },
+      // Some good parameters based on our dataset:
+      start_date: new Date(),
+      end_date: new Date(`2020 00:00`),


Probably better not to mix backticks and normal quotes

Haroenv · 2018-02-01T10:10:24Z

docgen/src/guides/calendar-widget.md

+In our connector instantiation, we need to attach the calendar and specify its callback function to refine the search. This part will be specific to the calendar library that you use in your app. In the Baremetrics Calendar, this function is passed to the `callback` argument.
+
+```javascript
+const makeRangeWidget = instantsearch.connectors.connectRange(


proposal: call the widget datePicker, since that's more consistent with the names in IS.js

Yeah, it's also more explicit!

vvo · 2018-02-01T10:40:34Z

Nice guide!

Advice on behaviour

I would like your advice on the calendar behaviour.

Since I am used to the AirBnB like calendar, it took me some time to understand how to use this one. Here's the difference:

If you just blindly click on the two dates and you endup clicking only on the "End date (second date)" then the behaviour is very confusing because you think you're gonna select start then end dates while it's not the case. You're only changing the end date.

Is there a way to have the default demo behaviour where every time the calendar is opened then the action is "select the start date, then the end date" and never "select only the end date".

For the demo

Could you add a link to the source code in the demo? So the user once he have seen the demo can jump into the code right away.

francoischalifour · 2018-02-01T10:57:22Z

I couldn't find a calendar widget without huge dependencies as good as react-dates UX-wise. This is definitely the pain point of this guide. I also had trouble getting familiar with the Baremetrics Calendar. I can try a workaround but it probably won't be very elegant.

As for the source code in the demo, I can add a link to the zip file.

bobylito · 2018-02-01T10:59:14Z

docgen/src/guides/calendar-widget.md

+
+Search results often need to be refined by dates. Calendars are a good visual way to improve the user experience when it comes to filtering dates. InstantSearch provides custom widgets to create reusable components within your app.
+
+By the end of this guide, you'll understand how to implement a calendar widget to refine your results based on a single date and a range of dates. You can [preview](https://community.algolia.com/instantsearch.js/v2/examples/calendar-widget/) and [download](https://community.algolia.com/instantsearch.js/v2/examples/calendar-widget.zip) the concert app that you'll be able to build.


Links should be relative.

Right, should I make all links relative or only these two?
I've seen some other guides using absolute links.

vvo · 2018-02-01T13:32:01Z

I can try a workaround but it probably won't be very elegant.

It's OK for now since we show how to plug a calendar. This one also has some cool features like last 30 days etc.. Which are great

As for the source code in the demo, I can add a link to the zip file.

I would add a link to zip yes but also the GitHub direct link, since you might just want to read the code without having to download and unzip

francoischalifour · 2018-02-01T13:39:17Z

@vvo What branch should I link it to? master? (that would be this link)

vvo · 2018-02-01T13:50:13Z

master yes since it's the branch tracking the releases (= doc website is master branch doc)

francoischalifour · 2018-02-01T14:14:21Z

All changes have been made and all dependant PRs have been merged 🙂

Thank you all for your feedback!

@Haroenv I've fixed the "Invalid date" issue on Safari.

vvo

LGTM for my own comments

bobylito · 2018-02-05T14:02:23Z

LGTM 👍 thanks for this awesome contribution @francoischalifour :)

francoischalifour added 3 commits January 31, 2018 17:04

docs(guide): add Calendar Widget Guide

0c8ac6c

docs(header): add the Calendar Widget Guide to the header

32ac846

docs(examples): add Calendar Widget demo

6122e8b

francoischalifour added DO NOT MERGE - Only for review Doc: Guide labels Jan 31, 2018

francoischalifour requested review from vvo and bobylito January 31, 2018 16:13

Merge branch 'develop' into docs/calendar-widget

9dfce50

Haroenv reviewed Feb 1, 2018

View reviewed changes

bobylito reviewed Feb 1, 2018

View reviewed changes

francoischalifour added 4 commits February 1, 2018 14:52

chore(guide): update guide

2f87e6a

chore(guide): update terminal screenshot

bee66c3

chore(demo): fix dates in Safari

09f8c80

chore(demo): add link to source code and zip

ef3a780

francoischalifour removed the DO NOT MERGE - Only for review label Feb 1, 2018

Haroenv and others added 3 commits February 2, 2018 09:53

Merge branch 'develop' into docs/calendar-widget

e474b98

Merge branch 'develop' into docs/calendar-widget

46fb311

chore: add link to dataset

cc9c3ea

francoischalifour mentioned this pull request Feb 2, 2018

Support search config override per documentation page #2690

Merged

francoischalifour and others added 2 commits February 5, 2018 11:32

chore(docs): remove name attribute

65a7b8f

Merge branch 'develop' into docs/calendar-widget

1f6f89b

vvo approved these changes Feb 5, 2018

View reviewed changes

bobylito merged commit 44096c0 into develop Feb 5, 2018

bobylito deleted the docs/calendar-widget branch February 5, 2018 14:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add guide "Create a Calendar Widget" #2687

Add guide "Create a Calendar Widget" #2687

francoischalifour commented Jan 31, 2018 •

edited

Loading

algobot commented Jan 31, 2018 •

edited

Loading

Haroenv left a comment

Haroenv Feb 1, 2018

Haroenv Feb 1, 2018

Haroenv Feb 1, 2018

bobylito Feb 1, 2018

Haroenv Feb 1, 2018

Haroenv Feb 1, 2018

francoischalifour Feb 1, 2018

bobylito Feb 1, 2018

Haroenv Feb 1, 2018

francoischalifour Feb 1, 2018

Haroenv Feb 1, 2018

bobylito Feb 1, 2018

Haroenv Feb 1, 2018

francoischalifour Feb 2, 2018

francoischalifour Feb 2, 2018

Haroenv Feb 1, 2018

Haroenv Feb 1, 2018

Haroenv Feb 1, 2018

francoischalifour Feb 1, 2018

vvo commented Feb 1, 2018 •

edited

Loading

francoischalifour commented Feb 1, 2018

bobylito Feb 1, 2018

francoischalifour Feb 1, 2018

vvo commented Feb 1, 2018

francoischalifour commented Feb 1, 2018

vvo commented Feb 1, 2018

francoischalifour commented Feb 1, 2018 •

edited

Loading

vvo left a comment

bobylito commented Feb 5, 2018


		Search results often need to be refined by dates. Calendars are a good visual way to improve the user experience when it comes to filtering dates. InstantSearch provides custom widgets to create reusable components within your app.

		By the end of this guide, you'll understand how to implement a calendar widget to refine your results based on a single date and a range of dates. You can [preview](https://community.algolia.com/instantsearch.js/v2/examples/calendar-widget/) and [download](https://community.algolia.com/instantsearch.js/v2/examples/calendar-widget.zip) the concert app that you'll be able to build.

Add guide "Create a Calendar Widget" #2687

Add guide "Create a Calendar Widget" #2687

Conversation

francoischalifour commented Jan 31, 2018 • edited Loading

algobot commented Jan 31, 2018 • 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

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

vvo commented Feb 1, 2018 • edited Loading

Advice on behaviour

For the demo

francoischalifour commented Feb 1, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vvo commented Feb 1, 2018

francoischalifour commented Feb 1, 2018

vvo commented Feb 1, 2018

francoischalifour commented Feb 1, 2018 • edited Loading

vvo left a comment

Choose a reason for hiding this comment

bobylito commented Feb 5, 2018

francoischalifour commented Jan 31, 2018 •

edited

Loading

algobot commented Jan 31, 2018 •

edited

Loading

vvo commented Feb 1, 2018 •

edited

Loading

francoischalifour commented Feb 1, 2018 •

edited

Loading