Refinement Lists

Overview

This component provides a set of tools to filter the results using different facets. If the user selects a combination of filters, the search will be updated with it.

This component must be linked to a search Store, since it retrieves the values of the last search results to filter.

Usage

This is how you create this component:

sdk.component('refinement-lists', target: HTMLElement|String, options: Object);

Sample

By default, this component looks like this:

Options

The following options can be set in this component:

Name Type Default Description
refinements Array [] Array with each refinement options.
refinements.*.attributeName String The attribute name to refine on
refinements.*.limit Number 10 The number of values to display
refinements.*.nullFacetString String '' The label of the null value refinement. Does not show if empty.
refinements.*.operator 'and' or 'or' 'or' Apply operator on refinement
refinements.*.sortBy Array ['isRefined:desc', 'count:desc', 'name:asc'] The sorting strategy for the refinement values. Available values are 'count:asc', 'count:desc', 'isRefined:asc', 'isRefined:desc', 'name:asc' and'name:desc'.
refinements.*.headerText String '' A text to display at the top of the component
refinements.*.showFacetCount Boolean true Show the count for each facet values
templates Object The templates to override the default render behavior
templates.item String | (Object) => String Item template, provided with:
  • count: The total number of results that contain the facet.
  • value: The name of the facet.
transformData Function (object) => object Function to transform the object sent to the view

Methods

The following methods can be used in this component:

Method Description
clearFilters() Removes all the applied filters.

Tracking

This component does a new search when applying filters, using the endpoint POST /federated-searches. This search is bound to the current session and the tracking option set to true.

Labels

This component uses the following labels:

Name Default Description
REFINEMENT_LISTS_SHOW_MORE Show more The text for the "show more filters" option
REFINEMENT_LISTS_SHOW_LESS Show less The text for the "show less filters" option
REFINEMENT_LISTS_TITLE FILTERS The text for the header title

Examples

Basic example using the results component Store, through the linkTo method:
<div id="colour-filters"></div>
<div id="results"></div>

<script>
  var results = sdk.component('results', '#results');
  var genderFilter = sdk.component('refinement-lists', '#colour-filters', {
    refinements: [
      {
        attributeName: 'COLOUR',
        headerText: 'Colour Filter'
      }
    ]
  });
  results.linkTo(genderFilter);
</script>
Example using templates
<div id="colour-filters"></div>
<div id="results"></div>

<script>
  var results = sdk.component('results', '#results');
  var genderFilter = sdk.component('refinement-lists', '#colour-filters', {
    templates: {
      item: '<span>{{ name }}</span> ({{ count }})',
      // or
      item: function (facet) {
        return '<span>' + facet.value + '</span> (' + facet.count + ')';
      }
    },
    refinements: [
      {
        attributeName: 'COLOUR',
        headerText: 'Colour Filter'
      }
    ]
  });
  results.linkTo(genderFilter);
</script>