Decoupled search with Drupal Search API

TLDR; The module Search API Decoupled now comes with a javascript client that works out-of-the-box. To test it simply add it to your Drupal installation and enable the demo sub-module. If you want to know about the architecture, where the code is, why we did it, and see some nice screencasts keep reading. If you want to get a demo come to our session at Drupalcon Lille 2023.

We contributed the module Search API Decoupled to allow the creation of engaging search experiences with client-side Javascript applications. 

In comparison to traditional server side search, client side solutions are much faster, because fetching and rendering search results is much more efficient then requesting full pages. 

We released the backend functionality of Search API Decouple in Drupal Dev Days 2023 in Vienna, the slides and video are available online.

However, Drupal needs a fully working search client so that developers and marketers can easily evaluate the functionality for their projects. 

Such a client should provide great search functionality out-of-the-box and should be easy to extend and style.

We applied for funding at the Drupal Innovation Contest Pitchburgh but we did not get it. 

But we decided to build and contribute the functionality anyway.

Since solutions built with Search API Decoupled consist of server-side and client-side functionality that is developed independently from one another, we decided that the Javascript client should be maintained as a separate project.

Drupal supports hosting of Javascript projects, so we created the source code repositories there:

• Drupal: Search API Decoupled Client
• Drupal: Search API Decoupled Client UI

For both projects we publish the corresponding packages to package manager npm:

• npm: Search API Decoupled / Client
• npm: Search API Decoupled / UI

The client libraries can then be included in the Drupal module as dependent libraries with composer.

These packages are included as dependent libraries with the Search API Decoupled UI sub-module using Composer.

As a result you have a fully working client-side search. To make testing easy we included a demo sub-module. Simply enable the sub-module and see the client side search in action.

Here is a screencast of how this works out-of-the-box with the Drupal theme Olivero and the demo configuration:

When trying it out locally make sure that you have the merge plugin for composer installed. For details see the project page.

As you can see from the screencast above the search integrates nicely with existing frontends. 

To customize the existing search widgets you can target the elements with CSS selectors.

To tailor the search to your needs change the widgets or re-arrange the layout in the backend UI of Search API Decoupled.

Here is a screencast how you can customize the search in the backend:

However, you can also override and extend the UI elements of the search app. This is the reason why we splitted the client-side search functionality in two packages. If you want to override, extend, or completely exchange the UI elements of the search app, you can use Drupal's library mechanism to remove the provided functionality and/or add your own.

For us at 1xINTERNET this is important, because we build our frontends with design systems and web components. The widgets used in search are part of our design system. Therefore, we unset the default UI library and use our internal one instead.

Here is a screencast of the search using custom widgets created as web components:

If you want to try out the search with web components you can launch a demo instance at https://www.1xinternet.de/en/try-drupal.

Last but not least we provide a great developer experience for contributing to the javascript client app. When you clone the repositories you can simply run a fully working stand-alone search app to test and develop functionality.

Simply connect it to any Drupal instance that has Search API Decoupled enabled and a search endpoint configured. 

This is what the development environment for the search app looks like:

We have lots of ideas on how to improve the search api decoupled and the client software.

Some of the ideas are:

• Allow server side search criteria
• Add layout options
• Expand the UI elements
  • Pager
  • …

We would love to get your feedback on the functionality. And of course we are looking for contributions to make it even better.