Plugin: Extra search - search preview

Other versions of this plugin may exist. Please ensure you are viewing the documentation for the version that you are currently using. If you are not running the latest version of your plugin we recommend upgrading. See: list of all available versions of this plugin.

Purpose

This plugin generates a link that enables a user to access the full set of extra search results for an extra search that is displayed in conjunction with faceted navigation. It is designed to be used with extra searches that show a few results from a search that selects a specific facet (such as a different tab in a set of tabs) within the same search.

Usage

Enabling the plugin

Enable the extra-search-search-preview plugin on your results page from the Extensions screen in the administration dashboard or add the following results page configuration to enable the plugin.

plugin.extra-search-search-preview.enabled=true
plugin.extra-search-search-preview.version=1.0.0
The plugin will take effect as soon as it is enabled.

Plugin configuration options

The plugin requires faceted navigation configuration with a facet category which is the target of the navigation.

The following options can be set in the results page configuration to configure the plugin:

  • plugin.extra-search-search-preview.config.<extra_search_name>.facet_name: The name of the facet which contains the category which is to be selected. e.g. Tabs, Format, Department.

  • plugin.extra-search-search-preview.config.<extra_search_name>.category_label: The label of the facet category. e.g. All results, PDF, Department of Science.

  • plugin.extra-search-search-preview.config.append_selected_facets: Determines if the selected facet categories should be carried across. Default is false.

Where:

  • <extra_search_name> represents the name of the extra search which is to be enhanced with the navigation link.

The above can be applied at either the search package or results page level. Any option that set at the search package level will be defined on all child results pages unless overridden.

Details

The Funnelback extra searches feature provides the ability to run additional searches alongside the main search. This is useful for providing supplementary information without disrupting the relevancy of the main search.

For example, extra searches can be used to show a carousel of 3 to 5 related social media results alongside the main search results.

Unfortunately, a limitation of extra searches is that there is no way for the user to see results beyond what is displayed. i.e. Extra searches do not provide navigation links which means that the user is unable to see more matching content from the same extra search.

This plugin addresses this limitation by generating navigation links based on facets (which can be configured via parameter keys) and adding to the data model so that it can more easily templated. The link is generated to the response.customData.stencils.searchPreviewLink element of the extra search:

customData": {
  "stencils": {
    "searchPreviewLink": "<SEARCH-LINK>"
  }
}

The FreeMarker snippet below can be used to present the link generated by the plugin:

<#--
    Show the more link which will allow the user to navigate
    to the corresponding tab or facet.
-->
<#if (response.customData.stencils.searchPreviewLink)!?has_content && (response.resultPacket.results)!?has_content>
    <#assign searchLink = question.getCurrentProfileConfig().get("ui.modern.search_link")!>
    <#assign previewLink = response.customData.stencils.searchPreviewLink!>

    <a href="${searchLink}${previewLink}" title="See more results">
        See more
    </a>
</#if>

Similar logic can be applied when accessing the JSON or XML data model directly.

## Examples

### Create a search preview for Facebook posts which directs the user to the social media tab

In this example, we want to create navigate links for a social media extra search which navigates the user to the social media tab.

The search is configured with:

* A search package (called `example~sp-search`) containing two data sources - `example~ds-websites` and `example~ds-facebook`
* A tabbed facet called _Tabs_ containing the following categories:
    * `Websites` which returns documents from `example~ds-websites` data source.
    * `Social media` which returns documents from the `example~ds-facebook` data source.
* An extra search called `social_media` which pulls content from `example~ds-facebook`

The following parameter keys need to be added to the results page configuration:

```ini
plugin.extra-search-search-preview.config.social_media.facet_name=Tabs
plugin.extra-search-search-preview.config.social_media.category_label=Social Media

This will produce the following under extraSearches.social_media.response.customData:

customData": {
  "stencils": {
    "searchPreviewLink": "?query=<query>&collection=example%7Esp-search&f.Tabs%7Cclient%7Efacebook=Social+media"
  }
}

This link can then be accessed from the search result template to give the user an option to view the complete set of extra search results.

Create a search preview for events which directs the user to the events while maintaining facet selection

In this example, we want to create navigate links for an events extra search which provides the ability for the user to navigate to the 'Events' tab. All facet selections are to be carried over.

The search is configured with:

  • A search package (called example~sp-search) containing data sources; example~ds-websites and example~ds-events

  • A tabbed facet called Tabs has been configured containing following categories:

    • Websites which returns documents from example~ds-websites data source.

    • Events which returns documents from the example~ds-events data source.

  • A checkbox facet called Department containing categories sources from department metadata.

  • An extra search called events which pulls content from example~ds-events.

The following parameter keys need to be added to the results page configuration:

plugin.extra-search-search-preview.config.events.facet_name=Tabs
plugin.extra-search-search-preview.config.events.category_label=Events
plugin.extra-search-search-preview.config.append_selected_facets=true

If a user runs a search and selects the department of science category from the department facet this will generate the following link to the data modelextraSearches.events.response.customData:

customData": {
  "stencils": {
    "searchPreviewLink": "?query=<query>&collection=client%7Esp-search&f.Tabs%7Cclient%7Efacebook=Events&f.Department%7Cdepartment=department+of+science"
  }
}

As you can see the department of science facet selection is included in the generated link so that the facet will be applied automatically when the link is clicked.

All versions of extra-search-search-preview