loading

Implementing Facets| Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

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

How to implement facets

In this section, you’ll learn how to implement facets within the Answers Search Configuration file (i.e., the backend configuration) as well as the Frontend configuration.

As a first step, you will need to set the custom field as a facet by making it a searchableField in your Search Configuration file. Facets are set at the vertical level.

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.

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) experiences 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.

light bulb
Tip
Adding additional components like filters includes a lot of “commenting-in”. You can easily do this via commands on your keyboard! Try doing cmd + / on a Mac or ctrl + / on a Windows.
  1. 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>
  2. 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.

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:

Video of interacting with facets on Turtlehead tacos

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 Filters for Facets

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.

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:

Image of Searchable Facets

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": {

facet order

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

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. Reach out in the Community if you’re implementing this - we’d love to hear more about your use case!
{
  "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.

unit Quiz
+20 points
Daily Quiz Streak Daily Quiz Streak: 0
Quiz Accuracy Streak Quiz Accuracy Streak: 0
    Error Success Question 1 of 2

    True or False: It is required to add the Facets object to ComponentSettings for them to work in the frontend.

    Error Success Question 2 of 2

    Which of the following can be modified in ComponentSettings?

    Climbing that leaderboard! 📈

    You've already completed this quiz, so you can't earn more points.You completed this quiz in 1 attempt and earned 0 points! Feel free to review your answers and move on when you're ready.
1st attempt
0 incorrect
Splash Loading