Featuring a video from Acro Media’s YouTube tutorial series Tech Talk, this article will walk you through setting up an awesome Drupal Commerce product catalogue using Search API and Solr, and then adding various ways of filtering the results (product search, sorting options and Facet categories).

The end result of this guide will be a catalogue that functions in the same way as our Urban Hipster Drupal Commerce demo site’s catalogue. You can try it here. If you don’t already know why we use Search API, Solr and Facets for catalogues, check out this article to get up to speed.

Even though we’re going to be using products, once you understand how it works you’ll be able to apply the same method for other type of content such as a blog, videos, resources, and more. The datasource can change but the process is the same.

Let's get started! Follow along with this video or skip below for a written guide.

What you need before starting

1. A running Solr server (Solr 6.4+)
   This tutorial assumes you have Solr running and can make a new core.
   
   
2. Drupal 8 installed with the following modules:
   
   TIP: Get most of what you need quickly with Commerce Kickstart. Note that you will still need to install the Facets module after getting your Kickstart package.
   
   
   • Commerce
     composer require drupal/commerce
   • Search API
     composer require drupal/search_api
   • Solr
     NOTE: This module requires you're running Solr 6.4+ and PHP 7
     composer require drupal/search_api_solr
   • Facets
     composer require drupal/facets

Getting started

1. Install/start Solr and add a new core that we’ll use later.
   
   
2. Enable the Commerce, Search API, Solr and Facets modules.

Setup a basic Commerce store

For this tutorial, get your site and basic store set up by doing the following:

1. Add a product category taxonomy vocabulary that is at least 2 levels deep.
   If we use clothing as an example, we might have Men and Women as the first level, then t-shirts, shorts and shoes as the second level for each.
   
   
2. Setup your basic Commerce store, product types and product variation types.
   If you’re new to Commerce, take a look at their documentation to get up and running quickly.
   
   NOTE: Make sure to add the taxonomy vocabulary you created as a ‘taxonomy reference’ field to your Product Type.
   
   
3. Add 10 or more simple products for testing the catalogue as we go.

Add a Search API server and index

Search API server

Admin: Configuration > Search and metadata > Search API
Admin menu path: /admin/config/search/search-api

1. Click ‘Add server’.
   
   
2. Configure the server.
   1. Name your server and enable it.
   2. Set ‘Solr’ as the server ‘Backend’.
   3. Configure the Solr connector.
      The defaults are usually fine. The main things to add are:
      • Solr connector = ‘Standard’.
      • Solr core = Whatever you named your core.
   4. Under ‘Advanced’, check ‘Retrieve result data from Solr’.
   5. Look over the remaining settings and update if you need to.

Search API index

Admin:Configuration > Search and metadata > Search API
Admin menu path:/admin/config/search/search-api

The index is where you set what data source is used by Search API. Eventually, you’ll also specify specific fields to be used for filtering the displayed results.

1. Click ‘Add index’.
   
   
2. Configure the index.
   1. Name your index.
   2. Data source should be ‘Product’
      This can be anything, but we’re creating a Commerce catalogue and so we want to use the store products.
   3. Select the server you just created.
   4. Save. Don’t add any fields for now, we’ll do that later.
   5. Go to the ‘View’ tab and index your results. This will index all of the products you have added so far.

Create a View for the catalogue

Admin:Structure > Views
Admin menu path:/admin/structure/views

The View will use the data source we’ve identified in our index and allow us to create a catalogue with it, and then assign ways of filtering the catalogue results (i.e. a search field and/or facets).

1. Create a new View.
   1. View Settings, select your index.
   2. Create a page (this will become our catalog).
2. View Display settings.
   1. Format > Show
      Set as ‘Rendered entity’, then in the settings, set your product types to use a ‘Teaser’ view mode instead of the default.
      
      NOTE: If you don't see the 'Rendered entity' option, this seems to be a bug with Views and happens when you don't select your index before checking the 'Create a page' checkbox. To fix this, just refresh your page to start over. If that doesn't work, flush your caches.
      
      NOTE:You may need to create this view mode if it doesn’t already exist.
      
      NOTE:You could alternately use Fields instead of view modes, but I like to keep my product display settings all within the product type’s display settings. Then you can potentially customize the display per product type if you have more than one.
3. Save the view .
   These basic settings should give us our overall catalog. You can confirm by previewing the view or visiting the page you just created.

Add Fulltext datasource fields for a catalog search field

Now we’ll start setting up a Fulltext search field to let our users filter results using a product search field. The first thing we need to do is add some datasource fields to our index that the search will use.

1. Go to your Search API Index and go to the Fields tab.
   
   
2. Add Fulltext fields that you would like to be searchable (such as Title, SKU, Category taxonomy name, etc.).
   Here’s an example for adding the title:
   1. Click ‘Add fields’.
   2. Under the ‘Product’ heading, click ‘Add’ beside the ‘Title’ field.
      
      NOTE: If you’re adding a different field instead, you may need to drill down further into the field by clicking ( + ) next to the field. For example, to make a taxonomy term a searchable field, you would go to Your Vocabulary > Taxonomy Term > Name .
      
      
   3. Click ‘Done’.
   4. Set the field ‘Type’ to ‘Fulltext’.
      This is an important step as only Fulltext fields are searchable with the user-entered text search we are currently setting up.
      
      NOTE: Under the fields section is a ‘Data Types’ section. You can open that to read information about each available type.
      
      
   5. Optionally change the ‘Boost’ setting.
      If you have more than one Fulltext field, the boost setting allows you to give a higher priority to specific fields for when the terms are being searched.
      
      For example, multiple products could have a similar title, but each product would have an individual SKU. In this case, SKU could be given a higher boost than title to make sure that search results based on the SKU come back first.
3. Next, add another field for the ‘Published’ status.
   
   
4. Once you’ve added this field, set it’s type as ‘Boolean’.
   
   
5. Reindex your data (from within the index view tab).

Set up the catalogue search field within the catalogue View

We can now set up the actual search field that our customers will use to find products, and use the datasource fields we added to our index to do this.

1. Go to your catalog View.
   
   
2. Under ‘Filter criteria’.
   1. Add ‘Fulltext search’ and configure its settings.
      • Check ‘Expose this filter to visitors, to allow them to change it’.
        IMPORTANT:This is what gives the user the ability to use this search field.
      • ‘Filter type to expose’, set as ‘Single filter’.
      • ‘Operator’, set as ‘Contains any of these words’.
      • ‘Filter identifier’, optionally adds an identifier into the url to identify a search term filter.
        (i.e. yoursite.com/products?your-filter-identifier=search-term)
      • Apply/save your settings.
   2. Add ‘Published’ and configure it so that it is equal to true.
      This uses the field we added to the index earlier to make sure the product is actually published. Chances are you don’t want unpublished results shown to your customers.
3. Under ‘Sort criteria’.
   1. Add ‘Relevance’.
   2. Configure so that the order is sorted ascending.
      This will show the more relevant results first (factoring in the boost you may have applied to your index fields).
4. Now we need to expose the search field to our customers. To do this:
   1. Open the ‘Advanced’ section of your catalog view.
   2. In the ‘Exposed Form’ area.
      • Set ‘Exposed form in block’ to ‘Yes’.
        This creates a block containing a search field that we can place on the site somewhere.
      • Set ‘Exposed form style’ to ‘Basic’ and update the settings. For now, the settings you might change are customizing the submit button text and maybe including a reset button.
5. Add the search block to your site.
   Admin menu path:/admin/structure/block
   
   
1. In your preferred region, click the ‘Place block’ button.
2. Find the Views block that starts with ‘Exposed form’ and click ‘Place block’.
   Its full name will be determined by you view’s machine name and page display name (i.e. Exposed form: products-page_1).
3. Configure the block as you see fit, and save.
6. Test your search!
   You should now be able to see the search field on your site frontend and try it out.

Add more datasource fields for sorting options

We can optionally sort the catalogue and search results with some additional sorting filters, such as sorting by Title, Price, Date added, etc. Let’s add the ability to sort our products by title with the option to choose ascending or descending order.

1. Go to your Search API Index fields and add another 'Title' field the same as you did earlier. However, this time you want to change the field ‘Type’ to ‘String’. You should now have two Title fields added, one as ‘Fulltext’ and one as ‘String’.
   
   NOTE: The field type can be different depending on what field you’re adding. If you’re adding a sorting field such as Price > Number, you might use the ‘Decimal’ field type.
   
   TIP: I would recommend changing the label for the new Title field to something like ‘Title for sorting’ so that it’s easier to identify later. You could even change the fulltext Title label to ‘Title for search’, just to keep them organized and easy to understand.
   
   
2. Reindex your data (from within the index view tab).
   
   
3. Go to your catalogue View.
   1. Under ‘Sort criteria’.
      • Add the new title datasource and configure it.
        • Check ‘Expose this sort to visitors, to allow them to change it’.
          IMPORTANT: This is what gives the user the ability to use this sorting option.
        • Add a label for the filter
        • Set the initial sorting method.
      • Add any additional sorting fields if you added more.
   2. Open the settings for the ‘Exposed form style’ (within the view’s ‘Advanced’ section).
      • Check ‘Allow people to choose the sort order’.
      • Update the labels as you see fit.
   3. Save your view!
      Refresh your catalogue page and you should now see sorting options available in the search block that you added earlier.
      
      TIP: If you DO NOT see the sorting options, this is a bug and is easily fixed. All you need to do is remove the search block and then re-add it.
      
      TIP: You can place this block in multiple regions of your site and hide the elements you don’t want to see with CSS. This way you can have a block with the site search and no filters in your header, and then also have another block on your catalog pages that shows the sorting filters but no search field.

Add Facets to the catalogue

The filters we added earlier can only be used one at a time, however, often we want to filter the results based on a number of different options. For example, if I’m browsing an online store looking for shoes of a certain style and size, I don’t want to see everything else the store has to offer. I want to be able to go to a ‘shoe’ category, then pick the ‘type’ of shoe that I’m after, and finally pick the ‘size’ of shoe that’s relevant to me. I want to see all of the results that fit that criteria. Facets lets you use taxonomy (and other datasources) to achieve this.

Let’s add a Facet that uses the taxonomy vocabulary we created in the initial store setup. This will be our main catalogue menu for narrowing down the product results. Each facet that is created creates a block that we can add into any region of our template.

1. Add a Search API index field for your taxonomy vocabulary. Set the field ‘Type’ as ‘String’.
   
   TIP: Like we did earlier, I would recommend renaming the label for this field to something like ‘Categories for Facet’.
   
   
2. Reindex your data (from within the index view tab).
   
   
3. Go to the Facets page.
   Admin: Configuration > Search and metadata > Facets
   Admin menu path: /admin/config/search/facets
   
   You should see a ‘Facet source’ available to use. When we created a View using our index, this is what added the Facet source here. Now that we have a source, we can create Facets to filter it.
   
   
4. Click ‘Add facet’.
   1. Choose the ‘Facet source’ to use.
   2. Select the index ‘Field’ that this Facet will use (i.e. Categories for Facet, or whatever you labelled your field).
   3. Name your Facet (i.e. Categories).
5. Configure the Facet.
   This will cover the basic settings that you will need. Start with this and then you can always play around with other settings later. Each setting has a pretty good description to help you understand what it does.
   1. Widget.
      Choose a ‘Widget’ for displaying the categories. For categories, I like to use ‘List of checkboxes’.
   2. Facet Settings.
      Check the following:
      • Transform entity ID to label.
      • Hide facet when facet source is not rendered.
      • URL alias as ‘cat’ (or whatever you like).
      • Empty facet behavior as ‘Do not display facet’.
      • Operator as ‘OR’.
      • Use hierarchy.
      • Enable parent when child gets disabled.
      • NOTE: the Facets Pretty Paths module can be used to give you nicer looking URL paths.
   3. Facet Sorting.
      Configure as you see fit. In this example, I would only check the following.These settings make sure that the taxonomy follows the same order that you have set within the vocabulary itself.
      • Sort by taxonomy term weight.
      • Sort order as ‘Ascending’.
   4. Save.
6. Add the Facet block to your site.
   Admin: Structure > Block layout
   Admin menu path: /admin/structure/block
   
   
   1. In your preferred region, click the ‘Place block’ button.
   2. Find the ‘Categories’ facet block (or whatever you named it) and click ‘Place block’.
   3. Configure the block as you see fit.
   4. Save.
7. Test your Facet!
   You should now see your Facet on the catalog page. Click the checkboxes and test out how it works!

One last thing...

The sites we've been building use the Facets Pretty Paths module for making nicer looking URLs with our catalog and filters. For a while we were plagued with a problem where, when the user selects a Facet category and then uses the sorting options, the Facets would uncheck and reset. This is obviously not good because the user is trying to sort the filtered down items, not the overall catalog. We need to be able to maintain the active facets when using the filters.

Luckily, a coworker came up with this nice little solutions that you can apply to your theme's .theme file. You just need to replace YOUR_THEME,YOUR-VIEW (i.e. products-page-1), and YOUR-PATH (i.e. products) in the code below. Ideally, this will be fixed within the module itself soon, but this will work while we wait.

/**
* Implements hook_form_alter().
*/
function YOUR_THEME_form_alter(&$form, FormStateInterface $form_state, $form_id) {
// Store - Product Listing view exposed form.
if ($form['#id'] == 'views-exposed-form-YOUR-VIEW') {
$current_path = \Drupal::request()->getRequestUri();

// If current path is within your catalog, correct the form action path.
if ((strpos($current_path, '/YOUR-PATH') === 0)) {
// Fix for views using facets with pretty paths enabled.
// Replace form action with current path to maintain active facets.
$form['#action'] = $current_path;
}
}
}

Done!

There you have it! You have now created a Search API index using Solr, setup a View to display the results of the index, and then implemented 3 different ways to filter the results (search, sorting and Facets). This is the start of an awesome product catalogue and you can expand on it with more datasource fields however you want. Cool!

Editor’s note: This article was originally published on July 12, 2018, and has been updated for freshness, accuracy and comprehensiveness.