Refinement Lists

Overview

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

To use this component, you need to use Filter components to create the different filter types. Besides, 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 with a facet filter:

Options

The following options can be set in this component:

Name Type Default Description
refinements Array [] Array with each refinement options.
refinements.*.headerText String '' A text to display at the top of the component.
refinements.*.component Object The filter component to use. See Filter components for more info. Use this property or the ones noted as '(Face filter)', but not both.
refinements.*.attributeName (Deprecated) String The attribute name to refine on. This option belongs to Facet filter component, see Facet filter
refinements.*.limit (Deprecated) Number 10 The number of values to display. This option belongs to Facet filter component, see Facet filter
refinements.*.nullFacetString (Deprecated) String '' The label of the null value refinement. Does not show if empty. This option belongs to Facet filter component, see Facet filter
refinements.*.operator (Deprecated) 'and' or 'or' 'or' Apply operator on refinement. This option belongs to Facet filter component, see Facet filter
refinements.*.sortBy (Deprecated) 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'. This option belongs to Facet filter component, see Facet filter
refinements.*.showFacetCount (Deprecated) Boolean true Show the count for each facet values. This option belongs to Facet filter component, see Facet filter
templates Object The templates to override the default render behavior (Facet filter)
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.
(Facet filter)
transformData Function (object) => object Function to transform the object sent to the view. (Facet filter)

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_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 colorRefinement = sdk.filterComponent('facet', { attributeName: 'COLOUR'});
  var colorFilter = sdk.component('refinement-lists', '#colour-filters', {
    refinements: [
      {
        headerText: 'Colour Filter',
        component: colorRefinement
      }
    ]
  });
  results.linkTo(colorFilter);
</script>
Example using templates
<div id="colour-filters"></div>
<div id="results"></div>

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