Skip to content

Working with facets

Facets is a concept allowing for dynamic and contextually based multiple choice product filtering and navigation of a defined dataset or a search result. Faceted navigation is also known as check-box navigation as it is most often visually presented for a visitor as check-boxes.

The Facets panel is at the core of the facets functionality. It returns all configured and available facet values based on its ingoing product filter, selected_category, or search_phrase arguments. Depending on if facets are used for category pages or filtering products in a search result, the arguments used to the Facets panel may differ.

Facet usage overview

Configuring facet attributes

Configure facet attributes before use

Filter attributes used for facets must be configured as such before use. Using attributes not correctly configured as facets will result in incorrect data selection and may break panel queries. Configuration is done in the Voyado Elevate manager.

Facet values are configured as a filter attribute where the Used in Facets property is set to either Values or Range. As with regular filter attributes, a facet must have a Type and a Refinement configuration. The filter attribute Type configuration determines how the facet can be used. When the Type configuration is set to string, the facet can be used as Values. When Type configuration is a numeric type, the facet can be used as Range.

Values

Configuring a facet to be used as Values means that the actual value of the facet, including a product count, is used. The Values setting requires the filter Type configuration to be string. The recommended refinement to use is Case insensitive which normalises the text content to lower case.

Additional facet attribute settings can be configured when using Values.

Setting Description
Sort by The sort order of facet values. Can be relevance, count, value, and selected. Defaults to relevance if not configured.
Number of values The number of facet values to return. Must be larger than 0.
Include zeros Include or exclude facet values that returns a product count of 0. Selecting a facet can cause another facet to return a product count of 0. Set Include zeros to true to include these facet values in the result. This setting should typically only be false when Sort by is set to value and a large number of facet values are returned. Defaults to false.
Keep order Keep the sort order between facet values or let other facets change the sort order. The sort order of facet values can change depending on which values that are selected in other facets. Set Keep order to true in keep the facet sort order regardless of selected values in other facets. This setting should typically only be false when a large number of facet values are returned for specific product selection and relevant facets must be on top of the list. Defaults to false.
relevance Setting of Sort by. The relevance sort order will present the most relevant values for the products in the selection. For more information, see Relevance.
count Setting of Sort by. The count sort order will present the most frequent values in the facet, with respect to the products in the selection, i.e. values occurring in the largest number of products will come first.
value Setting of Sort by. The value sort order will present the values sorted alphabetically on the text representation for each value.
selected Setting of Sort by. The selected sort order will present the values selected by the visitor first. The sort order is ignored if no selected facets are provided through the facets argument.

Values is often used with product attributes that are expressed as text or a mix of text and numbers such as size, color, brand, in stock, and other custom attributes.

Range

Configuring a facet to be used as Range means that a numeric range result with a minimum and maximum value will be used. The Range setting requires the filter Type configuration to be numeric, e.g. byte, double, float, int, long, or short. The refinement to use is (no refinement).

Range is often used with product attributes that are expressed as numbers such as price, dimensions (length, width, height, diameter, and depth), and weight.

Facet basics

The facets argument is used in panel queries to the Facets panel but also to the result panels it is used with, primarily the Product list panel for category pages or the Search hits panel for search results.

The product selection that determine facet availability is based results in the Product list panel or the Search hits panel. Using the Facets panel without one of those panels may result in unexpected facet availability.

All facets returned in a query to the Facets panel include a value selected based on the incoming facets argument. This value is a boolean and returned as either true or false.

Example

The following example is a query to a Facets panel, /facets-panel using the Web API JavaScript library and its utilities. An initial product filtering is performed with the aid of the filter builder utility.

Query

var api = window.esalesAPI({ market: '{market}', url: 'https://{cluster-id}.api.esales.apptus.cloud' });

var fb = new api.utils.FilterBuilder();
var facet = new api.utils.Facet();

var filter = fb.attribute('category', 'shirts');
facet.add('color', ['red','blue']).add('size',['S','M']);

api.panel('/facets-panel', {
    filter: filter.toString(),
    facets: facet.toString(),
    facet_order: 'facet_attributes',
    facet_attributes: 'color,size',
    locale: 'en-GB',
    max_facets: 3
}).then(function(data) {
    var returnedFacets = data.response;
}).catch(function(data) {
    console.log('Error: ', data);
});

var esalesObj = window.apptus.esales("{cluster-id}", "{market}");

var fb = new window.apptus.utils.FilterBuilder();
var facet = new window.apptus.utils.Facet();

var filter = fb.attribute('category', 'shirts');
facet.add('color', ['red','blue']).add('size',['S','M']);

esalesObj.panel("/facets-panel").fetch({
    filter: filter.toString(),
    facets: facet.toString(),
    facet_order: 'facet_attributes',
    facet_attributes: 'color,size',
    locale: 'en-GB',
    max_facets: 3
}).error(function(msg) {
    console.log("ERROR: " + msg);
}).success(function(data) {
    var returnedFacets = data;
});

Result

JSON 
{
   "resultType": "facetList",
      "facetList": [{
              "attribute": "color",
              "isRange": false,
              "values": [{
                  "text": "red",
                  "ticket": "-",
                  "count": 2,
                  "selected": true
              },
              {
                  "text": "blue",
                  "ticket": "-",
                  "count": 1,
                  "selected": true
              },
              {
                  "text": "grey",
                  "ticket": "-",
                  "count": 1,
                  "selected": false
              },
          {
              "attribute": "size",
              "isRange": false,
              "values": [{
                  "text": "S",
                  "ticket": "-",
                  "count": 2,
                  "selected": true
              },
              {
                  "text": "M",
                  "ticket": "-",
                  "count": 1,
                  "selected": true
              },
              {
                  "text": "L",
                  "ticket": "-",
                  "count": 1,
                  "selected": false
              }]
          }
      ]
}

Facets for category pages

The Facets panel is often used together with a Product list panel on category pages primarily showing products. The selected_category and filter arguments are often used with all panels to narrow down the product selection to get facet attributes and values from.

A common approach is to use the first selected facet value in a Facets panel as a new panel query to return a delimited product set within the active category. Each new selected facet value or change in a facet range can be used to delimit what further facet values can be selected.

For example, on a category page the first value selected is memory:16GB, the second value is storage:[129,256], and the third value is price:[750,1300]. The only selectable values left at this stage are storage:[275,512] and display:[13,14].

Product navigation with facets

Facets for search results

Two panels commonly used together on a search result page are the Search hits panel and the Facets panel. The Facets panel is used here to restrict the search result and limit what products are shown by the Search hits panel. This allows a visitor to use the facet attributes and their values returned from the product set to narrow down their product selection.

The search_phrase and search_attributes arguments must be supplied to both panels and the facet_attributes argument is recommended to be added in the query to the Facets panel.

Search result product filtering

Sorting facet attributes

The order facet attributes are returned to the Facets panel is primarily determined by the facet_order argument. The supported values for the argument are relevance and facet_attributes. If facet_attributes are used for sorting, an additional panel argument, facet_attributes, must be included with the attribute sort order otherwise it will default to relevance.

If the facets are configured as Values, their primary internal sort order are determined by the Sort by configuration of the facet attribute. The secondary sort order is automatic and is based on the actual content of the value. They are sorted numerically or lexicographically with character sorting according to the set locale.

Counting products

All facet values returned in a query have a count based on the incoming arguments to the Facets panel. The count represents the number of results that would match the value if the corresponding check-box on a page was selected by a visitor. So even though a check-box for a facet value is not selected by a visitor, the visitor can see the amount of products that this option includes.

It is recommended to keep facet values that return a count of zero.

Counting products with facets

Facets builder utility

The JavaScript libraries for both Web API v2 and Web API v1 includes a utility for creating facet (and filter) strings. It is recommended to use the facets builder utility when creating facets for panel queries via the JavaScript Libraries.

Panels supporting facets

The following predefined panels support a facets parameter with a panel query.

Best practice

  • Always include locale and max_facets in a query to the facets panel.
  • Set Include zeros and Keep order to true when using facets as Values. This will stop facets from changing positions in the interface while a visitor interacts with it, while at the same time allowing the visitor to see unavailable combinations. Facets with a count of zero should not be selectable by a visitor in the interface.
×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE