Confusion about instantsearch render event/option

So ‘render’ is mentioned in several contexts in the docs, and I’ve got questions about each…

Firstly, in the context of the instantsearch() event, no parameters are passed to the function correct? Example:

instantsearch.on('render', function (renderOpts, isFirstRendering) {
   blah blah blah
});

renderOpts and isFirstRendering are undefined. So this is pretty much only useful if you want to perform something on render without any condition based on the search performed, correct?

Secondly, in the context of the widgets, there is often a section called ‘Widget’. There is no example of how this is used, but I tried this:

search.addWidget(
  instantsearch.widgets.hits({
    container: '#hits-container',
    render: function(renderOpts, isFirstRendering) {
      myfunction based on hit data
    }
  })
);

Here, ‘render’ does nothing. It would be the most convenient place to add render logic based on whatever the widget returns, similar to how transformData works… but it doesn’t appear to do anything. Am I mis-interpreting the widget section on how to use ‘render’?

Thirdly… I have gotten the render function working via connector but the first argument is always undefined on first render… which is kind of irritating because the script will fail to load without logic to compensate. Example:

function hideresults(renderOpts, isFirstRendering) {
  if (isFirstRendering === true || renderOpts.results.query.length === 0) {
    $('.container.content-grid>.row').show();
    $('#algolia-results').hide();
  }
  else {
    $('.container.content-grid>.row').hide();
    $('#algolia-results').show();
  }
}
var autohide = instantsearch.connectors.connectHits(hideresults);
search.addWidget(autohide());

Here, reversing my OR statement will cause the script to not load on first render… not really a question, just nitpicking. The question I guess, is this the only way to use search/widget results in the render function?

Hi and thanks for the feedback. Indeed it’s hard to find the correct vocabulary for everything.

For the events, there are no information provided at this step. The fact that the callback has been called already gives you the information that the render has been done. This is useful if you wish to make a smooth transition when loading your first results.

Then on the widget side. There is another vocabulary issue here. hits, searchBox, refinementlist and others are actually widget factories. They are functions that return widgets. Widgets are simple objects that are defined by a specific contract, with at least an init or a render method. More information can be found in this guide. So indeed the widget factories never implement any render option because they do not make sense at this level.

For the connectors you have indeed a render function with the signature that you are using.

Besides all of those, render is one of the lifecycle step of the widgets and that’s why it’s always the same name in different context.

If you want to do some conditional logic each time you receive new information, you could do a custom widget like so:

search.addWidget({
  render: function(renderOptions) {
    // renderOptions contains four keys:
    //   - results: the results from the last request
    //   - helper: to modify the search state and propagate the user interaction
    //   - state: the state at this point
    //   - createURL: if the url sync is active, will make it possible to create new URLs
  },
});