Tutorial 2: Facets

In this tutorial, you will learn how to set up a facet-based filter on a product list page, enabling users to filter the list of products shown using e.g. radio buttons, checkboxes or dropdown menus (Figure 1.1).

Figure 1.1 Facets in action - here in the form of checkboxes

This tutorial presupposes that you have completed Tutorial 1 - if you haven't go back and follow the guide until the create a query step then switch to this guide.

A facet works by passing values from frontend to a query with a set of parameters, one per facet. The query then returns a result with products or content matching the query expressions - one of which takes a parameter as the testvalue.

We will be building a simple query matching active products from a particular manufacturer, with the test value passed to the query by a facet control.

  • Click Add query
    • Name it
    • Select your index as data source
    • Click OK
  • Click Add parameter
    • Name it (e.g. Manufacturer)
    • Select System.String as type
    • Click OK
  • Click Expressions > Add group
    • In the dropdowns, select the Active field and the Equal operator.
    • Click the pencil and select Constant and System.Boolean. Set value to true.
    • Click Add expression
      • Select the Manufacturer ID field
      • Select Match any as the operator
      • Click the pencil and select Parameter > Manufacturer
  • Save and close your query
Figure 2.1 Your expressions should look like this

Q: I'm using facets alongside Ecom navigation, and my facets disappear when I click on a subgroup in the navigation. Why?

A: You need to make sure you pass on a GroupID parameter to your query as well, as in Figure 2.2

Figure 2.2 Making Ecom navigation and facets work together

Technically, a facet is a mapping between a query parameter (e.g. Manufacturer) and a list of values from a field in the index (e.g. Manufacturer name) – selecting one of the values in frontend then passes the value to the query, and the filtered query result is then returned to frontend.

Facets are created inside facet groups - to create a facet group:

  • Click Add facets to create a facet group, then:
    • Name it
    • Select your query as the query for the facet
    • Click OK

This opens the facet group interface, from which you can create the facets you want to use:

  • Click Add field facet – a field facet will pull all the values from the Manufacturers field and make them into facet options (a drop down menu, in this case).
    • Name it - e.g. Manufacturers
    • Select the field Manufacturer ID from the dropdown
    • Select the query parameter Manufacturer you created before
    • Click OK
  • Save and close your facets window
Figure 3.1 Your field facet should look like this

As soon as the query is created you can pass values to it by adding the parameter and a value to the URL in the format ?[parametername]=[value] - but facets must be rendered using the FacetGroups loop. 

  • Create or open a paragraph with a product catalog app attached
  • In the app settings:
    • Under Show select Index
    • Under the Index settings select your query
    • In the Facet Groups selector include the facet group by moving it from left to right
  • In the Templates section open or create a product list template and use the FacetGroups loop to render controls for passing selected facet values to the query - see example below:
<form method="get" action="/Default.aspx"> <input type='hidden' name='ID' value='@Pageview.Page.ID' /> <h4>@Translate("FilterResult", "Filter your results")</h4> <table> @foreach (LoopItem group in GetLoop("FacetGroups")) { foreach (LoopItem facet in group.GetLoop("Facets")) { <tr> <td><i>@facet.GetString("Facet.Name")</i></td> <td> <select name="@facet.GetString("Facet.QueryParameter")"> <option value="">@Translate("None", "None")</option> @foreach (LoopItem option in facet.GetLoop("FacetOptions")) { var value = option.GetValue("FacetOption.Value"); var selected = option.GetBoolean("FacetOption.Selected"); var label = option.GetString("FacetOption.Label"); var count = option.GetInteger("FacetOption.Count"); <option value="@value" selected="@selected"> @label (@count) </option> } </select> </td> </tr> } } </table> <input type="submit" value="Apply filter" class="btn btn-primary" /> <a href="/Default.aspx?ID=@Pageview.Page.ID">Clear</a> </form>

The template above renders all facets in the facet group in the same way, but you can change the template above to switch which type of control to render, based on the data type of the value, or simply the name of the facet.

Which html elements to use, and which type of behavior they should have, is completely up to the implementer. Dynamicweb does not provide any predefined html elements for things like ranges or lists.

  • Save and close your module settings

And that’s it. You’re done!

Click Show page and start using your facets.