How to create a custom Facets query for your Drupal 8 faceted search app
When it comes to allowing users to search a site easily, a faceted search app can be an unparalleled solution. Being able to quickly drill down into search results using specific, easy-to-understand parameters is something that most users now simply expect from any site’s search app.
For Drupal 8 sites, the Facets module makes it relatively simple to create your own faceted search app, whether you’re using the Drupal core Search module or the very popular Search API module to manage your search functionality.
In the case of a site using Search API, the Facets module works particularly well in parallel with more powerful search engine backends like Apache Solr and Elasticsearch. Facets within a search app can take all shapes and sizes, and the Facets module provides a few plugins types that, in concert with each other, can be leveraged to programmatically create any sort of facet you may need for your search app. Because the Facets module relies on the Entity API within Drupal 8, these plugins should appear relatively familiar to most Drupal 8 developers:
\Drupal\facets\Entity\Facet- Describes the facet entity itself, whose data is received via a widget plugin and parsed by processor plugins
\Drupal\facets\Entity\FacetSource- Describes the source of the data being fed into the facet
\Drupal\facets\QueryType\QueryTypePluginBase- Describes the type of query being made against the search backend.
\Drupal\facets\Widget\WidgetPluginBase- Describes the widget that the user interacts with to control the search UI.
\Drupal\facets\Processor\ProcessorPluginBase- Describes the processor that translates the user input from the widget into data that can be used within the query.
The Facets module (along with its submodule Facets Range Widget) provides 4 basic query types:
\Drupal\facets\Plugin\facets\query_type\SearchApiString- The most comment facet query type, based on searching for simple strings.
\Drupal\facets\Plugin\facets\query_type\SearchApiGranular- Used for numbers-based facets that provide a spectrum of values between a set step size.
\Drupal\facets\Plugin\facets\query_type\SearchApiRange- Used for queries that allow users to select a range of possible numerical values.
\Drupal\facets\Plugin\facets\query_type\SearchApiDate- Used for queries to allow users to choose (ranges of) date values.
NOTE: These query types are to be used within the context of a Search API backend, rather than the Drupal core Search module.
So how do we do it?
I’d like to offer a brief example of how you might go about writing your own custom query types for a faceted search app using the Search API and Facets modules.
In our recent scenario, we needed a way to allow users to query against our search backend using numerical values, but in the format of comparing their chosen number value against searchable values using a specific comparison operator. In this case, our users were students who needed to be able to search for specific academic or volunteer programs. They also needed to be able to filter results based on a length of time (in weeks) that would be greater than or less than a specified value.or example, users would need a facet that allowed them to filter results by: any length of time, 1+ weeks, 2+ weeks, 3+ weeks, etc.
With this requirement in mind, the 4 basic query types listed above were not quite up to the task. Instead, we needed to write a custom "Integer Comparison" query type that would take in two key pieces of data. A number to compare values against and a comparison operator with which to make those comparisons. From our example use case above, we only needed the number from the user, because we would be setting the comparison operator (“>=“ AKA “greater than or equal to”) in configuration. However, we wanted to write a generic enough query type that could allow for any basic comparison operator in the future. This is the result:
In the code above, the two key pieces of data (the user-input number and the configuration-defined comparison operator) are $value['int’] and $value['op’]. However, in order to get these two simple values, we also needed to write a custom processor that could receive the raw input in from our facet widget and process that input into those two simple $value['int’] and $value['op'] values.
To understand what’s happening in the preQuery method above, you just need to know that the slider widget we implemented on the frontend had its possible data values encoded in a format like this:
Finally, in the code above, you’ll notice the one method getQueryType(), which is needed to specify which query type the processor should pass its data along to (in this case, our custom integer_comparison query type). In order to make our new query type plugin and processor plugin aware of each other, we need to implement one last hook in our module:
Contributed Customization
We're always looking for ways to customize integrations to fit the specific needs of project goals and we understand that out of the box solutions aren't always going to work. For example, the Facets module itself provides a submodule called Facets Range Widget that allows users to search using a range of numbers or dates. However, the default behavior of this facet assumed the use of a bounded range, as opposed to what we needed, which was an infinite range starting from a definite value. In that case, it was simpler for us to quickly create the exact facet query type that we needed, rather than wrestling with the defaults provided by the Facets module. We were only able to do that thanks to the Facets module’s highly extensible plugin system that leverages the contributed Search API and core Entity API of the Drupal ecosystem. That is why, even when we have a need for custom code, it is always a helpful first step to start from the strong contributed code provided by the Drupal community.