connectors connectStarRating

Edit this page

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

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

const makeStarRating= instantsearch.connectors.connectStarRating(
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

  • attributeNamestring

    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.connectStarRating(renderFn);

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


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