feat(queryRules): add queryRuleCustomData widget

[francoischalifour]

This is the 2nd PR in the series "Merchandized Query Rules".

Summary

This creates the queryRuleCustomData widget, responsible for showing custom data (userData) coming from Query Rules.

Current solution

Right now, we can leverage the connectHits connector to show a banner with InstantSearch.js.

const promotedResults = instantsearch.connectors.connectHits(
  (options, isFirstRender) => {
    const { widgetParams, results = {} } = options;
    const { container } = widgetParams;

    if (!results.userData) {
      container.innerHTML = '';
      return;
    }

    const [data] = results.userData;

    container.innerHTML = `<img src="${data.banner}" alt="${data.link}">`;
  }
);

search.addWidget(
  promotedResults({
    container: document.querySelector('#promoted-results'),
  })
);

See live example →

The goal of the widget is to simplify this solution.

Widget usage

Given this userData:

{
  "banner": "https://website.com/image.png",
  "title": "This is a revolution.",
  "link": "https://website.com/"
}

When the query rule is matched, the engine returns:

[
  {
    "banner": "https://website.com/image.png",
    "title": "This is a revolution.",
    "link": "https://website.com/"
  }
]

You would use the queryRuleCustomData widget:

instantsearch.widgets.queryRuleCustomData({
  container: widgetContainer,
  transformItems: items => items[0],
  templates: {
    default({ title, banner, link }) {
      if (!banner) {
        return '';
      }

      return `
        <h2>${title}</h2>

        <a href="${link}">
          <img src="${banner}" alt="${title}">
        </a>
      `;
    },
  },
});

API

transformItems

object[] => any – defaults to items => items

The function to change the data sent by the engine before giving it to the template.

container

string | HTMLElement – no default

The container of the widget.

templates

object – defaults to { default: '' }

The templates to display for the custom data (userData).

Stories

See stories →

Related

• connectQueryRules
• queryRuleContext
• Merchandized Query Rules RFC

[algobot]

Deploy preview for instantsearchjs ready!

Built with commit 2684259

https://deploy-preview-3600--instantsearchjs.netlify.com

[francoischalifour]

GitHub seems to also display the changes introduced in #3599, that's weird.

[Haroenv]

These changes seem to be a different PR? Not sure what to review here

[Haroenv]

I think the base might be wrong :)

[francoischalifour]

As said in #3600 (comment) I think that's a GitHub bug. You can ignore the changes related to Storybook.

Edit: I rebased again, should be fixed!

[francoischalifour]

Without custom CSS classes, the inserted div container is not easily customizable because nothing identifies it.

I think we should create an InstantSearch.css spec for this widget with the following markup:

<div class="ais-QueryRuleCustomData"></div>

It would imply adding a cssClasses option to the widget, like in most widgets.

WDYT?

[Haroenv]

makes sense to me!