Drupal Module

SearchStax recently announced the availability of a Drupal Module that integrates SearchStax Site Search running on Apache Solr 8 with a Drupal 8 or 9 environment. This page discusses how to install and configure the module.

The Drupal SearchStax integration module was developed jointly with Thomas Seidl (a.k.a. drunken monkey), the renowned creator and maintainer of the Drupal Search API. The SearchStax integration module follows all Drupal open source code guidelines and is available in the Drupal project at https://www.drupal.org/project/searchstax.

Setup

Setting up the Drupal Module is an easy, step-by-step process that you can complete in just a few minutes.

Requirements

The SearchStax module requires two other Drupal modules to work correctly:

  • Search API: Provides a comprehensive way of adding advanced search functionality to Drupal sites.
  • Search API Solr: For using an Apache Solr server (as provided by SearchStax) together with Search API.

Install these two modules before installing the SearchStax module.

Installation

You can install the SearchStax module like any other Drupal module:

  1. Add the module’s code to your Drupal installation. There are multiple ways to do it:
    • Download an archive with the latest release from the module’s project page and then unpack it somewhere inside your Drupal installation’s /modules folder;
    • or use Composer, executing the command: composer require drupal/searchstax.
  2. Then, enable the module, either on Drupal’s Extend page (/admin/modules) or via Drush (drush en searchstax).
Figure 1: Enable the module on the Drupal Extend page.

Configuration

After enabling the module, you will need to configure a few options to start working with SearchStax and Site Search on your Drupal site. For this, navigate to the module’s configuration page in one of the following ways: either by clicking Configure next to the module on the Extend page; or navigating to Administration » Configuration » Search and metadata » SearchStax settings on your Drupal site; or by entering the URL yoursite.com/admin/config/search/searchstax manually into your browser’s URL bar.

Figure 2: You can navigate to the SearchStax module’s configuration page by clicking Configure on the Extend page after enabling the module.

The configuration page contains the following options (subject to change):

  • Global analytics key: The analytics key to use by default for tracking searches, results clicks, etc. Retrieve it from your Site Search account, by navigating to Apps Management and then opening the Analytics API tab.
  • Search-specific analytics keys: In case you have several apps defined in Site Search, you can use this section to change the analytics key used for every single search page on your site. (In case a search page is not listed here, its searches will also not be tracked!)

In case you only have a single search app configured, you can safely ignore this section.

  • Auto-suggest core: (Only displayed if the Search API Autocomplete module is installed on your site.) If you want to use SearchStax’s auto-suggest capabilities, enter the Solr core to use into this field. You can find this in your Site Search account, under Apps Management » Search API » Suggest URL. The core is the second to last component – between /solr/ and /emsuggest.
  • Re-route searches through Site Search: Enable this option in case you want to use SearchStax’s own handler for search requests instead of the one provided by Search API Solr. If this is disabled and you use Search API (not StudioJS) for creating a search page, most of the search settings in your Site Search account will not have any effect.
  • Configure searches exclusively via Site Search: If this option is enabled, most search settings configured in Drupal will be ignored and the settings configured in Site Search will take effect. This includes, for instance, sorting, searched fields and field boosts. Only fulltext keys, filters, paging parameters and facets will be passed to the Solr server.
  • Configure facets via Site Search: (Only displayed after enabling Configure searches exclusively via Site Search option): If this option is enabled, facet parameters will also not be sent to the Solr server and the Site Search facet settings will be used. This will in most cases not work correctly with the Facets module, so custom code handling the returned facets will be needed. (This setting has no effect if no facets have been configured in Drupal.)

With all of this configured as desired, simply click “Save configuration” to complete the setup.

Figure 3: The SearchStax module configuration page.
Figure 4: How to retrieve the analytics key for your account.
Figure 5: How to find the identifier of the auto-suggest Solr core in your Site Search account.
Figure 6: An example of a filled-out configuration form.

Add auto-suggest to your searches (optional)

Auto-suggest (or auto-complete) refers to providing a site visitor who is typing search keywords into a search box suggestions for what keywords to try. This not only helps them save time and avoid typos, but also could provide them with new ideas what to search for, or how to better phrase what they are looking for. Site Search provides a very sophisticated algorithm for keyword suggestions, suggesting those combinations of words for which visitors actually clicked any result links. Therefore, enabling auto-suggest with Site Search can be a great addition for your site’s search experience.

If you want to add auto-suggest to searches provided by Drupal directly, then you will need to have the Search API Autocomplete module installed on your site. Once that is done and you have specified the Auto-suggest core in the SearchStax configuration form, you can then configure any search on your site to use auto-suggestions provided by Site Search, by following the steps below:

  1. Navigate to the Administration » Configuration » Search and metadata » Search API configuration page, then proceed to the search index which the search page in question uses and finally to its Autocomplete tab.
  2. There, you see a list of all search pages on your site known to the Search API module. (These are the same ones for which individual analytics keys could be selected above.) If not done already, enable autocomplete for the search in question, then click the Edit button next to it.
  3. On this page, you have many options for customizing autocomplete for this search. To let suggestions be provided by Site Search, check SearchStax as the (or one of the) Enabled suggesters. (If choosing more than one suggester, please also remember to order them as desired with the widget right below the checkboxes.)
  4. Make any other adaptions you want to the autocomplete settings for the search (none of them are specific to SearchStax) and then click Save.

You should now see suggestions when typing into the search’s keywords field, provided by Site Search. (On development sites, it could be the case that no suggestions are displayed until enough tracking data, including search result clicks, are available.)

Figure 7: Navigate to the Autocomplete tab of your search index, then enable autocomplete for the search in question and click Edit.
Figure 8: Enable the SearchStax suggester to start providing search suggestions from Site Search to your visitors.

Module Functionality

Tracking Search Results

Search results are automatically tracked for all searches known to the Drupal Search API module. No further configuration is needed. You can verify which searches are “known to the Drupal Search API module” by going to the SearchStax configuration page and seeing which searches are listed under Search-specific analytics keys.

In case you use custom code on your site to display a search page and your search is not listed there, you have to provide a Search API “Display” plugin for your search. See the Search API documentation for details. This will also allow other modules, like Facets and Search API Autocomplete, to work with your search, so is good practice in any case.

Tracking Search Results Clicks

As there are a lot of different ways how search results, and the associated result links, are generated in Drupal, the SearchStax module cannot reliably provide support for tracking search result clicks for all of them. A best effort is made to at least provide click tracking out-of-the-box for the most common setups for the two most popular ways of generating search pages, Views and Search API Pages.

Technical Information

For seeing whether your search is already supported, execute a search with keywords, then open your browser’s development tools pane (Network tab) and finally click on any search result. In the Network tab you should then see a request to a URL like https://app.searchstax.com/api/v2/track/?data=DATA, where DATA is a base 64-encoded JSON string with the tracking data. It should contain "event":"_searchclick".

Please contact us if you want to add click tracking for another search. In any case, you can use the _searchstax_add_tracking() helper function provided by the SearchStax Drupal module to implement this. You can also see examples for this in the searchstax.module file.

Auto-suggestions Provided by Site Search

In combination with the Search API Autocomplete module, provide suggestions to visitors when they enter search keywords, backed by the Site Search suggestion engine.