connectors connectRatingMenu

Description

StarRating connector provides the logic to build a custom widget that will let the user refine search results based on ratings.

The connector provides to the rendering: refine() to select a value and items that are the values that can be selected. refine should be used with items.value.

Usage

const search= instantsearch(/* parameters */);

const makeStarRating= instantsearch.connectors.connectRatingMenu(
  function renderFn(
      renderOpts: StarRatingRenderingOptions,
      isFirstRendering: boolean) {
    // render the custom StarRating widget
  }
);

const  customStarRating = makeStarRating(instanceOpts: CustomStarRatingWidgetOptions);
search.addWidget(customStarRating);

Connector options

StarRatingRenderingOptions

• itemsArray<StarRatingItems>

  Possible star ratings the user can apply.

• createURL(string) => string

  Creates an URL for the next state (takes the item value as parameter). Takes the value of an item as parameter.

• refine(string) => undefined

  Selects a rating to filter the results (takes the filter value as parameter). Takes the value of an item as parameter.

• hasNoResultsboolean

  true if the last search contains no result.

• widgetParamsObject

  All original CustomStarRatingWidgetOptions forwarded to the renderFn.

StarRatingItems

• namestring

  Name corresponding to the number of stars.

• valuestring

  Number of stars as string.

• countnumber

  Count of matched results corresponding to the number of stars.

• starsArray<boolean>

  Array of length of maximum rating value with stars to display or not.

• isRefinedboolean

  Indicates if star rating refinement is applied.

CustomStarRatingWidgetOptions

• attributestring

  Name of the attribute for faceting (eg. “free_shipping”).

• max[number]
  Default value: 5

  The maximum rating value.

Example

// custom `renderFn` to render the custom StarRating widget
function renderFn(StarRatingRenderingOptions, isFirstRendering) {
  if (isFirstRendering) {
    StarRatingRenderingOptions.widgetParams.containerNode.html('<ul></ul>');
  }

  StarRatingRenderingOptions.widgetParams.containerNode
    .find('li[data-refine-value]')
    .each(function() { $(this).off('click'); });

  var listHTML = StarRatingRenderingOptions.items.map(function(item) {
    return '<li data-refine-value="' + item.value + '">' +
      '<a href="' + StarRatingRenderingOptions.createURL(item.value) + '">' +
      item.stars.map(function(star) { return star === false ? '☆' : '★'; }).join(' ') +
      '& up (' + item.count + ')' +
      '</a></li>';
  });

  StarRatingRenderingOptions.widgetParams.containerNode
    .find('ul')
    .html(listHTML);

  StarRatingRenderingOptions.widgetParams.containerNode
    .find('li[data-refine-value]')
    .each(function() {
      $(this).on('click', function(event) {
        event.preventDefault();
        event.stopPropagation();

        StarRatingRenderingOptions.refine($(this).data('refine-value'));
      });
    });
}

// connect `renderFn` to StarRating logic
var customStarRating = instantsearch.connectors.connectRatingMenu(renderFn);

// mount widget on the page
search.addWidget(
  customStarRating({
    containerNode: $('#custom-rating-menu-container'),
    attribute: 'rating',
    max: 5,
  })
);

Can't find what you are looking for? Open an issue, we'll get back to you.