Configure a Basic Faceted Tree - BloomReach Experience - Open Source CMS
07-01-2019

Configure a Basic Faceted Tree

Introduction

Goal

Configure a basic faceted node tree in the content repository which can be used to render a faceted navigation in the delivery tier.

Background

Faceted navigation leverages content metadata fields and values to provide users with relevant filters to create and refine search queries in an incremental way.

Implementing faceted navigation in a Bloomreach Experience Manager implementation project requires two steps:

  1. Configure a virtual faceted node tree in the content repository.
  2. Implement navigation of the faceted node tree in the delivery tier.

This page describes the most basic form of step 1. 

Example

Create a Faceted Tree with Minimum Configuration

This example is based on a default implementation project created using the Maven archetype, with the "News" feature added.

The "News" features comes with 3 example news documents. To make the example a bit more interesting, use the CMS to add some more news document. Make sure to enter values in their Date, Author, and Source fields.

The minimum configuration for a faceted tree requires:

  • A node of type hippofacnav:facetnavigation with a name of your choice.
  • A String property hippo:docbase, the value of which should be the UUID (or multiple comma-separated UUIDs) of the source folder(s) for the faceted tree. All documents in that folder and its subfolders will be included.
  • A multi-valued String property hippofacnav:facets, of which each value is the name of a document property to use as a facet in the faceted tree.

For example, to create a basic faceted tree of news documents, using their Author and Source fields as facets to navigate the tree, follow the following steps:

Look up the UUID of the news folder. For example:

/content/documents/myproject/news:
  jcr:primaryType: hippostd:folder
  jcr:uuid: d2b1775c-fb97-4080-bd66-ede4ac874b5a

Create a faceted-news node as follows:

/content/documents/myproject:
  /faceted-news:
    jcr:primaryType: hippofacnav:facetnavigation
    hippo:docbase: d2b1775c-fb97-4080-bd66-ede4ac874b5a
    hippofacnav:facets: [myproject:author, myproject:source]

After writing the changes to the repository, you will see a number between square brackets behind the faceted-news node's name. The number indicated the total number of results.

If you expand the faceted-news node, you will see three new child nodes, each also with a number between square brackets behind their name:

/content/documents/myproject:
  /faceted-news [30]:
    jcr:primaryType: hippofacnav:facetnavigation
    /myproject:author [27]:
      jcr:primaryType: hippofacnav:facetsavailablenavigation
    /myproject:source [27]:
      jcr:primaryType: hippofacnav:facetsavailablenavigation
    /hippo:resultset [30]:
      jcr:primaryType: hippo:facetresult

The first two child nodes correspond to the facets your configured (myproject:author and myproject:source). These nodes provide the entrances to different drill-down paths into the content.

The third child node (hippo:resultset) contains a flat list of all results at the current drill-down path. This one simply contains all results because no drill-down path has been selected at this level.

Expand the myproject:source node to see its child nodes:

/content/documents/myproject:
  /faceted-news [30]:
    /myproject:author [27]:
    /myproject:source [27]:
      /onehippo.com [15]:
      /GoGreen [9]:
      /hippo:resultset [27]:
    /hippo:resultset [30]:

The child nodes (except hippo:resultset) each represent a value of the myproject:source property. In the example above, there are 15 documents with the value "onehippo.com" and 9 with the value "GoGreen".

All (visible) folders and document variants are included in the faceted tree, therefore the numbers you see in the Console may be higher than you expected (each document is counted three times). The delivery tier users normally only see either live or preview variants, so in a website each document is only counted once. It's also possible to configure a filter to only include, for example, live document variants.

The hippo:resultset again contains all results at this level. In this case, that means all documents that have a myproject:source property.

From this point on, you can combine any number of facets and facet values in any order by navigating down the tree. Each facet value further refines the result set.

The example below shows the result set when facet myproject:source with value "GoGreen" and facet myproject:author with value "Sonja Verde" are selected:

/content/documents/myproject:
  /faceted-news [30]:
    /myproject:author [27]:
    /myproject:source [27]:
      /onehippo.com [15]:
      /GoGreen [9]:
        /myproject:author [9]:
          /Robert Greene [3]:
          /Sonja Verde [6]:
            /myproject:author [6]:
            /myproject:source [6]:
            /hippo:resultset [6]:
              /sustainable-business-award:
              /sustainable-business-award:
              /sustainable-business-award:
              /record-growth:
              /record-growth:
              /record-growth:
        /myproject:source [9]:
        /hippo:resultset [9]:
      /hippo:resultset [27]:
    /hippo:resultset [30]:

Add Pretty Names

By default, facet nodes in a faceted tree are names after the corresponding values of hippofacnav:facets. Use the multi-valued String property hippofacnav:facetnodenames to specify 'pretty names' for the facet nodes:

/content/documents/myproject:
  /faceted-news:
    jcr:primaryType: hippofacnav:facetnavigation
    hippo:docbase: d2b1775c-fb97-4080-bd66-ede4ac874b5a
    hippofacnav:facets: [myproject:author, myproject:source]
    hippofacnav:facetnodenames: [Author, Source]

The number of values and the order of the values of hippofacnav:facetnodenames must match those of hippofacnav:facets.

The example below shows the resulting faceted tree:

/content/documents/myproject:
  /faceted-news [30]:
    /Author [27]:
    /Source [27]:
    /hippo:resultset [30]:

Configure Multiple Root Nodes

If you want to use more then one source folder, you can use a comma separated list of UUIDs in the hippo:docbase property:

/content/documents/myproject:
  /faceted-news:
    jcr:primaryType: hippofacnav:facetnavigation
    hippo:docbase: d2b1775c-fb97-4080-bd66-ede4ac874b5a,121916d1-1a36-4ea4-a4f2-32797c456ee9
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?