connectors connectMenu

Description

Menu connector provides the logic to build a widget that will give the user the ability to choose a single value for a specific facet. The typical usage of menu is for navigation in categories.

This connector provides a toggleShowMore() function to display more or less items and a refine() function to select an item. While selecting a new element, the refine will also unselect the one that is currently selected.

Requirement: the attribute passed as attribute must be present in “attributes for faceting” on the Algolia dashboard or configured as attributesForFaceting via a set settings call to the Algolia API.

Usage

const search= instantsearch(/* parameters */);

const makeMenu= instantsearch.connectors.connectMenu(
  function renderFn(
      renderOpts: MenuRenderingOptions,
      isFirstRendering: boolean) {
    // render the custom Menu widget
  }
);

const  customMenu = makeMenu(instanceOpts: CustomMenuWidgetOptions);
search.addWidget(customMenu);

Connector options

MenuRenderingOptions

• itemsArray<MenuItem>

  The elements that can be refined for the current search results.

• createURL(item.value) => string

  Creates the URL for a single item name in the list.

• refine(item.value) => undefined

  Filter the search to item value.

• canRefineboolean

  True if refinement can be applied.

• widgetParamsObject

  All original CustomMenuWidgetOptions forwarded to the renderFn.

• isShowingMoreboolean

  True if the menu is displaying all the menu items.

• toggleShowMorefunction

  Toggles the number of values displayed between limit and showMore.limit.

• canToggleShowMoreboolean

  true if the toggleShowMore button can be activated (enough items to display more or already displaying more than limit items)

MenuItem

• valuestring

  The value of the menu item.

• labelstring

  Human-readable value of the menu item.

• countnumber

  Number of results matched after refinement is applied.

• isRefinedboolean

  Indicates if the refinement is applied.

CustomMenuWidgetOptions

• attributestring

  Name of the attribute for faceting (eg. “free_shipping”).

• limit[number]
  Default value: 10

  How many facets values to retrieve.

• showMore[boolean]
  Default value: false

  Whether to display a button that expands the number of items.

• showMoreLimit[number]
  Default value: 20

  How many facets values to retrieve when toggleShowMore is called, this value is meant to be greater than limit option.

• sortBy[Array<string>|function]
  Default value: ['isRefined','name:asc']

  How to sort refinements. Possible values: count|isRefined|name:asc|name:desc.

  You can also use a sort function that behaves like the standard Javascript compareFunction.

• transformItems[(Array<object>) => Array<object>]

  Function to transform the items passed to the templates.

Example

// custom `renderFn` to render the custom Menu widget
function renderFn(MenuRenderingOptions, isFirstRendering) {
  if (isFirstRendering) {
    MenuRenderingOptions.widgetParams.containerNode
      .html('<select></select');

    MenuRenderingOptions.widgetParams.containerNode
      .find('select')
      .on('change', function(event) {
        MenuRenderingOptions.refine(event.target.value);
      });
  }

  var options = MenuRenderingOptions.items.map(function(item) {
    return item.isRefined
      ? '<option value="' + item.value + '" selected>' + item.label + '</option>'
      : '<option value="' + item.value + '">' + item.label + '</option>';
  });

  MenuRenderingOptions.widgetParams.containerNode
    .find('select')
    .html(options);
}

// connect `renderFn` to Menu logic
var customMenu = instantsearch.connectors.connectMenu(renderFn);

// mount widget on the page
search.addWidget(
  customMenu({
    containerNode: $('#custom-menu-container'),
    attribute: 'categories',
    limit: 10,
  })
);

Can't find what you are looking for? Open an issue, we'll get back to you.