Creating a Banner with InstantSearch Based Off of A Specific Filter

This article is to help walk you through setting up a banner with InstantSearch that is triggered when a user selects a specific filter.

Its based of of our documentation that can be found here :

Also you can find an implementation example at the following code sandbox :

Step 1 Tracking when a facet is changed

One option to trigger a banner rule based on a filter would be to set a Query rule context by using the trackedFilters option of our InstantSearch queryRuleContext widget:https://www.algolia.com/doc/api-reference/widgets/query-rule-context/js/#widget-param-trackedfilters

This context can then be used to trigger your rule.

Firstly we can add the InstantSearch widget that will set the Query Rule context when the user selects a filter, in this case we want to track the Movie or Music filters:

/**
* Here is where we track that movie has been selected
*/

search.addWidget(

instantsearch.widgets.queryRuleContext({

trackedFilters: {

Type: () => ['Movie', 'Music'], // So this attribute is only set when the type is Movie or Music is selected

},

})

);

With this widget added, if we select the facet value we are tracking

We will then see that the context is being sent with any search request where this facet value has been selected:

Screenshot-2020-07-03-at-12-00-55.png

You can see that the rule context is named ais- + The name of the facet + The name of the facet value that has been selected

We can then use this context to trigger our rule.

Step 2 Creating the rule.

The next step is to create a rule that will trigger the content for our banner.

2.a First we navigate to the rules section of the index we will be using for the banner and then create a new rule for our banner

2.b Select a new rule

2.c Select manual editor

2.d Enter the condition we want to trigger the banner to appear in the conditions field and select add in the dropdown that appears:

2.e Now select add consequence

2.f Choose return custom data, this is where we will put the data for the banner:

2.g The data is formatted as a JSON object which is basically a set of keys and values for the different fields that our banner needs to have. Here is the data we will use for this example:

{
"text": "Triggering rules with a context of ais-Type-Music"
}

The key message will be the text that shows in our banner and the key link is the link we will use for the banner link

2.h We paste this in as our custom data in the query rule.

Step 3. Displaying the banner:

This step will need to be carried out by your front end developer, there are two places you need to make a change, the file (probably an html file or similar) that contains the HTML for your search and the JavaScript file where you have your InstantSearch logic.

3.a First we place an HTML

element where the banner should appear in your HTML:

<div id="banner"></div>

3.b Now we create a queryRuleCustomData widget that contains the html for our banner, this needs to be added with the rest of your InstantSearch widgets:

// This has been added so we can see that the rule has been triggered by the context

instantsearch.widgets.queryRuleCustomData({

container: '#banner',

templates: {

default: `

{{#items}}

<p>{{text}}</a></p>

{{/items}}
`,
},
}),

We put it with our other InstantSearch widgets.

3.c Now we can test that the rule is triggered when we select the facet.

4 Customizing the banner

One we have the rule working we can customize the banner, to add extra attributes just modify the Custom JSON Data you return with your rule, you will also need to make changes in the template section of the queryRuleCustomData widget:

instantsearch.widgets.queryRuleCustomData({

container: '#banner',// the link to the HTML element that we placed where we want the banner to show

templates: {

default: `

{{#items}}

<h2>Special offer <a href={{link}}>CLICK HERE</a></h2>

<p>{{message}}</p>

{{/items}}

`, // We can access the fields we added to our custom data in the rule by using their name

},

}),