Implementing Facets | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How to add facets to the Search configuration and frontend configuration.

Overview

There are a few parts to implementing facets:

• Knowledge Graph content: As mentioned in the Searchable Fields Best Practices unit , facets work best with structured fields with a finite number of options. You’ll want to use categorical data.
• Search backend configuration
• Search frontend configuration

You’ll also be able to customize how facets show up to users in the frontend configuration. In this unit, we’ll cover both the backend and frontend Search configuration.

How to Implement Facets

Search Backend Configuration

As a first step, you will need to set the field as a facet under searchableFields in your Search backend config. Facets are set at the vertical level. You can do this in either the JSON editor or the UI.

For example, the c_track field is set as a facet here:

"searchableFields": {
  "builtin.entityType": {
    "nlpFilter": true
  },
  "c_mainEventText": {
    "textSearch": true
  },
  "c_track": {
    "facet": true
  },
  "c_sessionEventType": {
    "nlpFilter": true,
    "textSearch": true
  },
  "c_speakerCompany": {
    "textSearch": true
  },
  "keywords": {
    "nlpFilter": true,
    "textSearch": true
  }
}

Now that you have set your facet in the backend, you will need to make sure it appears in the frontend experience.

Search Frontend Configuration

Like adding other components from the SDK, there are two main steps in the frontend:

• Adding the component to the HBS file
• Adding any additional configuration in the JSON file

Additionally, we highly recommend pairing the facets (and sorting) with Collapsible Filters. This UI is optimized for mobile users, making it easier and more intuitive to sort and filter. The instructions below will outline how to add both Facets and Collapsible Filters.

Note

Adding additional components like filters includes a lot of “commenting in”. You can easily do this via keyboard shortcuts: try cmd + / on a Mac or ctrl + / on a PC.

Page pages.html.hbs file

Make sure to add (or “comment in”) the following lines for the Facets component script and markup, as well as the corresponding <div>:

Scripts - just Facets

{{> templates/vertical-full-page-map/script/facets}}

Markup - just Facets

  {{> templates/vertical-full-page-map/markup/facets}}  

Scripts - Collapsible Filters

  {{> templates/vertical-full-page-map/collapsible-filters/page-setup }}
  {{> templates/vertical-full-page-map/script/verticalresultscount }}
  {{> templates/vertical-full-page-map/script/appliedfilters }} 

Markup - Collapsible Filters (some may be commented in by default)

  {{> templates/vertical-full-page-map/markup/verticalresultscount }}
  {{> templates/vertical-full-page-map/markup/appliedfilters }} 
  {{> templates/vertical-full-page-map/collapsible-filters/markup/filterlink }}
  {{> templates/vertical-full-page-map/collapsible-filters/markup/viewresultsbutton }}    

This will use the default settings for facets from the SDK and filterlink from the Theme. Depending on the page template you’re using (e.g., vertical-standard vs. vertical-full-page-map), there may be additional instructions in the comments about class name updates or divs you’ll need to comment-in. For example, in the vertical-standard page template, you want to add and uncomment the following:

<div class="Answers-filtersWrapper js-answersFiltersWrapper CollapsibleFilters-inactive">
</div>

Page config.json file

If you want to modify any of the default settings, you can add a Facets object and FilterLink object in ComponentSettings in the JSON file. If this is commented out in your file, make sure to remove both the opening (/**) and closing (**/). For the full and most up-to-date list of Facet configuration options, you can reference the Facets section of the library documentation .

For Collapsible Filters to work, you’ll also need the componentSettings.AppliedFilters object defined and componentSettings.VerticalResults “hideResultsHeader” set to true. (These should be set by default when you go to add the page.)

Some popular settings to configure include expand and showMore, as you can see below. These properties control how the facets are displayed. The label object changes the name of the facet itself, which by default will otherwise match the name of the field in Knowledge Graph. The expand object can be used to collapse the facet options by default and the showMore object can be implemented when you have a large number of options so that the options do not take up the entire left side of the page. You can also set showMoreLimit and showMoreLabel and many more as you can see in the library documentation.

Here’s an example of what it would look like to specify these:

"Facets": {
  "expand": false, 
  "showMore": true,
  "fields": {
        "c_restaurantFeatures": {
              "label": "Restaurant Features"
        }
    }
},

This would render the following result:

Additionally, it’s worth calling out, as we mentioned in previous modules, that your vertical results can also display facets in the Applied Filters bar as you can see here:

Applied Filter settings can be modified in either your Universal Results or your Vertical Results component, where you have the ability to customize key aspects. For example, you can also set these filters as removable, which will allow that when clicked will remove the filter and trigger a new search. For the full list of settings for Applied Filters you can modify, you can reference the Universal Results and Vertical Results section of library documentation.

Now that we’ve implemented facets, the rest of the unit will walk through how to make changes to optional display configurations.

Searchable Facets

You will also notice from the library documentation that you can set if a facet is ‘searchable’. This can be done for all facets (set “searchable”: true) or on a field by field basis in the ComponentSettings in the JSON file. This can be especially useful when you have long lists of facets. Here’s an example of making only the restaurant features field searchable:

{
  "componentSettings": {
    "Facets": {
      "fields": {
        "c_restaurantFeatures": {
            "label": "Restaurant Features", 
            "searchable": true,
            "searchLabelText": "Search for our features",
            "placeholderText": "Search"       
        }
      }
    }
  }
}

When you add searchable facets to a field, a searchbar will appear above the facet options. As the user types, the facet options refine with each letter, such as:

Setting Facet Order

You can set the order in which facets appear on the frontend by editing your backend Search Configuration for each vertical object. If you don’t specify, the algorithm will determine this for you.

To do this, include a property called facetOrder in your vertical and include an array of facet fields in the order you want them to appear.

   "restaurants": {
      "entityTypes": [
        "restaurant"
      ],
      "name": "Restaurants",
      "savedSearchId": "112002255",
      "facetOrder": [
        "c_restaurantType",
        "c_restaurantFeatures"
      ],
      "searchableFields": {

Any facets that appear on a given search that are not stated in the facetOrder field will be shown in an arbitrary but consistent order, chosen by the algorithm.

Setting Facet Options Order

Starting in Theme 1.25, you can also set the order in which facet options appear in the frontend by editing the config.json file for each vertical. By default, facet options are ordered by the number of options per facet. However, you may also choose to set them in alphabetical (or reverse alphabetical) order or by a custom order.

To do this, set either optionsOrder or optionsOrderList in the fields configuration of the Facets object.

• Use optionsOrder to sort facet options alphabetically. Specify either “ASC” for alphabetical or “DESC” for reverse alphabetical. Note that facets on numbers will be stored as strings. You’ll need a custom sorting function to handle numbers correctly.

  {
  "componentSettings": {
  "Facets": {
    "fields": {
      "insurancesAccepted": {
          "placeholderText": "Search",
          "optionsOrder": "ASC"
      }
    }
  }
  }
  }

• Use optionsOrderList to set a custom order for the facet options. Provide the full list of case sensitive display names in an array.

  • Any options not provided will be displayed at the end of the list, ordered by result count.

  • In the case that an option is included in the array, but has zero results, the option will not display in the frontend.

    {
    "componentSettings": {
    "Facets": {
    "fields": {
    "c_daysOfTheWeek": {
        "placeholderText": "Search",
        "optionsOrderList": ["Monday", "Tuesday", "Wednesday", "Thursday","Friday", "Saturday", "Sunday"], //array, ["Monday", "Tuesday"]  
    }
    }
    }
    }
    }

Note: Only one of optionsOrder and optionsOrderList should be defined. If both are defined, optionsOrderList will take precedence and you will see a build warning in your console.