How to Add Instantsearch JS widgets and their common attributes
All Instantsearch widgets are added to the page in a similar fashion and they also share a number of common options that we’ll cover in this video. We will be playing with a dummy menu widget that won’t be part of the final project just to showcase all those options.
Instructor: [00:01] In order to demo how to add widgets and their generic parameters, we're going to create a demi-menu that will not be part of the project, but useful to understand the common mechanisms. Let's start by adding a div container to the HTML page and give it an ID of test widget. That's where our widget will be injected.
[00:24] Now, we move to the app.js file. We'll first declare a constant named test widget that will hold our widget. We now need to create it. Widgets are accessible from the instantsearch.widgets, then the widget of your choice. Here, we'll use the menu.
[00:41] Then we need to configure it, passing it a configuration object. Configurable attributes of widgets can be different depending on the widget's purpose. For this video, we'll focus on the ones that are shared across most of them. We will discover the others as we implement them.
[01:00] The first attribute to consider is the container. The container represents the location where the widget will be rendered in your HTML page. Its value can either be a CSS selector or a DOM element. Here, in our case, we'll add a string with hashtag test widget that refers to the div with an ID of test widget we've added before.
[01:22] Then we need to add the attribute name for this widget. Attribute name is common to all widgets targeting a facet or a filter attribute. In our e-commerce data set, each record contains a type attribute. Let's filter on type.
[01:37] Now that we have the container and the attribute name, that's enough for the menu widget to do its job. Last step before our widget can be displayed on-screen, we need to pass our test widget constant to the search.addwidget method. Refreshing the index page, we can now see that our widget displays correctly.
[02:00] Back to our widget configuration, another common widget attribute is the templates. Templates are a way to customize the rendering of a widget. They can only be written for some specific parts of the rendered widget, for example, header, item, footer, etc. When accessing specific values, this template can be written using Mustache or a function.
[02:24] Here, let's start by customizing the header with a plain string type. Saving and refreshing our browser, we now have a nice header on top of our widget.
[02:35] The final common widget attribute to cover is transform data. Transform data is used to provide functions that will pre-process the data passed to the templates. Those functions map the different template keys available when it makes sense. For example, if a widget accepts an item template, then you can use item and transform that item, modify it.
[02:57] For this example, let's just add a shortened version of each item label. We'll add a new property ellipsis to each item. We'll take the original value string and keep only the five first characters followed by three dots and we return the whole item object. Note that this is simply passed to the item template. Nothing special would show until we make use of our new item property.
[03:23] Let's implement our item template. Using Mustache, we can access the new items' ellipsis property. Refreshing the page, we have our facet value truncated after the fifth character.
[03:38] That wraps up the most common attributes used by most widgets. The final note on adding widgets, a shorter way to write it is to omit the constant declaration and moving the widget's creation directly inside the add widgets method, like so.