Instantsearch.js: Add a widget for helper configuration

[bobylito]

Following up on #1027, letting the user provide its own configuration for the internal search configuration using searchParmaters can be confusing because it relies on the internal structure of the helper state which is poorly documented.

But the helper and the state are objects that can be used for this configuration much more easily. It is also much more straightforward as it doesn't require knowledge of the structure but on using methods.

We could easily provide a widget that let the user access either the state or the helper. I think that using the state would be better as it contains more fine grained methods and also some that are not directly accessible on the helper, such as setFacets / setDisjunctiveFacets. It is also documented.

The API could look like :

search.addWidget(instantsearch.widgets.configurator(function (state) {
  return state.setFacets(state.facets.concat('myOtherFacet'))
              .addFacetRefinement('myOtherFacet', 'a value');
}))

What do you think? @redox @vvo @pixelastic

[redox]

Definitely make sense to create something dedicated to handle that 👍

If we go for a widget, I think we need to continue to iterate on the configurator naming.

That being said, I'm not a big fan of exposing the state API, it's one more API to understand to dig into instantsearch.js; I would keep manipulating the helper.

One other option could be to pass the configurator to the start function :)

search.start(function configurator(helper) {
  helper.addFacetRefinement('myOtherFacet', 'a value');
  helper.addDisjunctiveFacetRefinement(/* ... */);
});

Wouldn't that be easier to understand?

[pixelastic]

Agreed that it's easier to manipulate the helper than the underlying structure. Not sure I would have used a widget for that, seems to far from what a widget should do.

Not sure about passing it to the start method either. This looks like a quick win but adds one more place where users can configure the default behavior. I would stay with an instanciation option, something like helperConfiguration.

[bobylito]

Configurator is the best I could find so far :P Any other suggestion?

Do instantsearch users already use the helper? If not then exposing the SearchParameters makes no difference in terms of API learning, doesn't it? I'm ok to change the helper, but this kind of API raises other questions like is it a change if you add facet?

Also the Helper API is much powerful that what I would like to expose in this context. You can add event listeners and trigger the search...

I don't think yet adding yet another option makes things easier. The widget is trivial, and doesn't raise new questions in the reader/learner mind and it doesn't clutter the core.

I would stay with an instanciation option, something like helperConfiguration

I don't understanding how this is different from @redox suggestion?

[bobylito]

I did a draft PR ^

[redox]

Do instantsearch users already use the helper? If not then exposing the SearchParameters makes no difference in terms of API learning, doesn't it? I'm ok to change the helper, but this kind of API raises other questions like is it a change if you add facet?

The helper is what they need to use while building custom widgets; so for sure they are (and will more and more) use it.

Also the Helper API is much powerful that what I would like to expose in this context. You can add event listeners and trigger the search...

Good point, but I don't think it's a big deal.

I don't think yet adding yet another option makes things easier. The widget is trivial, and doesn't raise new questions in the reader/learner mind and it doesn't clutter the core.

The "widget" is trivial, but not the underlying state (nothing complex, just everything is new).

I would stay with an instanciation option, something like helperConfiguration

I think @pixelastic is just proposing something declared as an instantiation option to help having every "initial setup" dong at the very same place. I'm fine with that. Maybe we could name that option init or something meanings "put here a function to configure the underlying helper" because helperConfiguration looks more like an object rather than a function.

[vvo]

:+1: on advocating to use the helper.methods. The SearchParameters is not official as a user facing API.

What we want to do here is already doable by using searchFunction parameter, but I agree this is not straightforward.

Creating a custom widget or adding a new option, we will still need to add a FAQ entry containing "Setting default parameter at launch".

What about having configureHelper callback in instantsearch option? I was first fine with a new widget but feel like this would look weird because it's really only configuring the helper, not adding anything to the DOM nor configuring the url bar.

[bobylito]

I have the feeling that the configureHelper function as a callback option in the instanciation feels hardcoded whereas a widget feels modular. Everything that can be done as a widget should.

The idea when creating the SearchParameters object was not to hide it to the users (and it is official API). But it sure fails to be on par with the helper interface which makes a poor choice for now.

[pixelastic]

I would rather keep the widgets for everything that is DOM/UI related. That's what we always push when we explain the library.

I would follow the same path as what we did with the urlSync. For the end-user it is just a new option to pass to the main instanciation object, even if internally we can handle it as a widget. Let's keep the user-facing API simple, and let's re-use the internal mechanism we are already used to. Best of both worlds.

And yes, we should definitely expose the helper more and not the state. We'll have to work on revamping the helper doc on the side as well

[Haroenv]

This can be revisited, since we use Configure for react-instantsearch. There we decided on a widget/component, even though it's not DOM.

As @alexandremeunier noticed when using Configure, it isn't immediately obvious why you need a component for that, and not do it on the InstantSearch component. I think we decided on a component to keep a clear distinction between algolia/helper params and things used in instantsearch.

[bobylito]

We have two proposals: make a widget, add a configuration option (either in instantsearch(options) or start(setState)).

The widget approach pros:

• separate the logic into a separated element
• does not add to the current API

The configuration option pros:

• Much better control over the lifecycle
• Close to the searchParameters approach
• Make sense if it's a one time configuration at the beginning

The widget approach would be close to react-instantsearch, but the two libraries are quite different: instantsearch.js offers a static configuration whereas react-instantsearch is dynamic. Also react-instantsearch does not offer any access to the helper. That's why it's a requirement for react-instantsearch and not so for instantantsearch.js.

[bobylito]

Closing this one for now. The tools are available if need be.