How do I use the new Current Search Blocks module?

Issue Summary

The Current Search Blocks module now bundled with Facet API allows site builders to create, manage, and configure blocks that contain information about the search being executed. The following steps are an overview of what the module provides and how site builders can use it. The first step is enabling the Current Search Blocks module which has a dependency on Facet API. Users with the administer search permission can create and manage configurations at admin/config/search/current_search. The configurations are managed by CTools, so there is a familiar interface that allows you to perform common operations such as adding, importing, editing, disabling, deleting / reverting, exporting, and cloning configurations.

When adding a configuration you have to give it a name and select which searcher, or search page, the current search block will be active on. If your site has multiple search pages, you can reconfigure this setting later by visiting the block's configuration page as illustrated in a later step.

After saving the configuration, you can add "items" to the current search block. Facet API provides site builders with three core items: custom text, a list of active items, and a list of active items grouped by field. Items are plugins, so module developers can create their own and contribute them back to drupal.org.

Once items are added, their display order can be set through the drag and drop interface. Each item provides additional configurations in the vertical tabs at the bottom of the page. Many of the configurations allow for search results aware tokens, so dynamic messages can be displayed.

Examples of the core plugins are illustrated below. The example also shows how multiple current search blocks can be active on the same search page.

Each configuration exposes a block that needs to be enabled in a region in order to be displayed on the search page. Each current search block is prefixed with "Current search:" and followed by the name of the configuration as shown in the example above.

Although site builders select the searcher when the configuration is created, it can be changed later on via the block's configuration page. Each current search block adds a "Search Page" visibility setting as shown below: