Filter & sort on categories

The WEBSALE | search module not only enables the classic product search, but can also be used for filtering and sorting on category pages. This way, customers can narrow down the displayed products by criteria such as color, price, or availability, and display them in a desired order. This documentation describes how the filter and sort function for categories is integrated into the shop. Two scenarios are distinguished:

If the search & search result page has already been integrated into the shop, many required components are already in place, and only targeted adjustments are required for the category templates.
If no WEBSALE search is used (e.g. because an external provider such as Findologic or FACT Finder is responsible for the search), the necessary components and scripts must be fully included for the category pages.

The following sections explain which adjustments are required for the different scenarios and which WebComponents and scripts must be used for a smooth integration.

Scenario: search & search result page already integrated

Already existing components

If the search has already been implemented in the shop, the following components are already included in all templates and do not need to be integrated again:

WEBSALE JavaScript library
JavaScript bundle (ws-search-component-<version identifier>.js)
Communication component (ws-search)
Search input field with optional suggest function (ws-search-box)
Search event dispatcher & forwarding of search queries (wsResultDispatcher.subscribe)

Adjustments for the category page (`ws_category.htm`)

For the category template ws_category.htm, only the following additional adjustments then need to be made:

Inclusion of the ws-search-result component
Template placeholder for the product box (<template id="resultItemTemplate">)
Filtering of the category products via ws-filter
Optional: include/exclude switch for individual filters via ws-filter-toggle
JavaScript for rendering the filters
Sorting of the category products via ws-sort-box
Pagination / paging of the category products via ws-pagination

Extension of the existing communication component

The <ws-search> component may only appear once in the template. Since it has already been included for the search & search result page, for the category page only the parameter category="" with a breadcrumb output without a separator needs to be added.

{ST-CatPage}
  {CAT-PathData}
  ~DC-FPparamList_set~

	~DC-Counter1_reset~
	{@CAT-PathRegular}
		{!DC-Counter1(0)}~DC-FPparamList_append(/)~{/!DC-Counter1(0)}
		~DC-FPparamList_append($CAT-Name$)~
		~DC-Counter1_inc~
	{/@CAT-PathRegular}
  {/CAT-PathData}
{/ST-CatPage}

<ws-search url="https://~WS-ShopID~.search.websale.net/api" subshop="~WS-SubShopID~" version="1.0" {ST-CatPage}category="~DC-FPparamList_urlencoding~"{/ST-CatPage}></ws-search>

Scenario: no existing search integration

If the shop search runs via external providers such as Findologic or FACT Finder, the WEBSALE search is not integrated. In this case, for the filter and sort functions on category pages, all required components must be explicitly included for the category template (ws_category.htm). The following guide describes the necessary adjustments to correctly integrate filtering and sorting via the WEBSALE search module.

Provision of the required resources

For the search module to work on the category page, the following resources must be included:

WEBSALE JavaScript library

The WEBSALE JavaScript library provides all relevant JavaScript modules for the search module as well as other standard shop functions. There are two variants of the library:

ws-system-<version identifier>.js - WEBSALE JavaScript modules including the jQuery library.
ws-core-<version identifier>.js - WEBSALE JavaScript modules without jQuery. In this case, jQuery must be included separately.

You can find more information in the documentation for the WEBSALE JavaScript library as well as in the overview of the available versions and modules.

If the WEBSALE JavaScript library is already included for other shop functions, it does not need to be integrated again.

JavaScript bundle

WEBSALE provides the JavaScript bundle ws-search-component-<version identifier>.js. This is required for the functionality of the filter and sort components. You can include the bundle via the WEBSALE PageSpeed tool or download it directly at:

http://<your-domain>/$WS/ws_sysdata/js/ws-search-component-<version identifier>.js

If you would like to make individual adjustments to the filter or sort logic, the JavaScript bundle can be modified.

Communication component

In addition to the JavaScript bundle, the ws-search component is required. It is provided by WEBSALE and is used for the communication between the frontend, the backend, and the integrated WebComponents. This component may only appear once per template.

{ST-CatPage}
  {CAT-PathData}
  ~DC-FPparamList_set~

	~DC-Counter1_reset~
	{@CAT-PathRegular}
		{!DC-Counter1(0)}~DC-FPparamList_append(/)~{/!DC-Counter1(0)}
		~DC-FPparamList_append($CAT-Name$)~
		~DC-Counter1_inc~
	{/@CAT-PathRegular}
  {/CAT-PathData}
{/ST-CatPage}

<ws-search url="https://~WS-ShopID~.search.websale.net/api" subshop="~WS-SubShopID~" version="1.0" {ST-CatPage}category="~DC-FPparamList_urlencoding~"{/ST-CatPage}></ws-search>

You can find more details about the communication component in the detailed documentation for the ws-search component. For the filter and sort functions to be used correctly, the ws-search-box component must be included technically - even if it is not actively used for the search.

<ws-search-box></ws-search-box>

You can find more details about the component in the detailed documentation for ws-search-box.

Search event dispatcher for filter & sort

The following script ensures the correct rendering of the filter and sort functions and should be included in the <head> of the template.

<script>
	// Subscribes to the search-result event and processes the results
	wsResultDispatcher.subscribe("result", function(resultData) {
		console.log(resultData); // Outputs the JSON response in the console
		var wsPayload = "ws_loadtpl_pl=y";
		var wsResultList = resultData.results;
		var wsPayloadIds = "";

		// Read product numbers and prepare them for further processing
		for (var i = 0; i < wsResultList.length; i++) {
            var productId = wsResultList[i]._id;
            var containerId = "wsProductWebComponent-" + productId;
            var container = document.getElementById(containerId);

          // Container exists AND does NOT contain an already loaded product box
          if (container && !container.querySelector('[id^="wsProductBox-"]')) {
              wsPayloadIds += "&ws_pl_" + (i + 1) + "=";
    		  wsPayloadIds += wsResultList[i]._id;
          }
		}

		// If product numbers were found, execute AJAX request
		if (wsPayloadIds !== "") {
			ws_AJAXloadTemplatePOST(
				"~WS-AJAXLoadTpl(incl_productbox.htm)~",
				"~WS-Charset~",
				ws_AJAXloadProductBoxStart,
				ws_AJAXloadProductBoxError,
				'ws_AJAXloadProductBoxResponseSuccess()',
				'ws_AJAXloadProductBoxResponseError()',
				wsPayload+wsPayloadIds
			);
		}
	});

	// Empty functions for AJAX events (can be overridden as needed)
	function ws_AJAXloadProductBoxStart() {};
	function ws_AJAXloadProductBoxResponseSuccess(parent) {};
	function ws_AJAXloadProductBoxError() {};
	function ws_AJAXloadProductBoxResponseError() {};

    ~DC-FPTemplate_set($WS-TemplateName$)~
    {!DC-FPTemplate(ws_search.htm)}
		// Event listener for new search queries (forwards to the search result page)
	document.addEventListener("wsPerformSearch", function (event) {
    	event.preventDefault();
      if(event.detail.query !== undefined && event.detail.query !== "") {
         location.href = "~URl-Homepage~?act=search&query=" + encodeURIComponent(event.detail.query);
      }
		return false;
	});
	{/!DC-FPTemplate(ws_search.htm)}
</script>

Function of the script

Detects when new search results or filter results are available.
Loads the product boxes via AJAX.
Enables a smooth filter and sort experience.

Integration of the products

The integration for the products on the category template must be adjusted as follows:

Using the ws-search-result component

The <ws-search-result> component processes the data from the search module and displays the filtered products on the category page.

<ws-search-result use-ajax="yes"></ws-search-result>

You can find details about how this component works in the detailed documentation for ws-search-result.

Template placeholder for the product box

To avoid height shifts when loading the product boxes, a <template> can be specified inside ws-search-result. This is displayed as soon as the product box is loaded. To define the template for the placeholders, result-placeholder must be specified at the slot:

<ws-search-result use-ajax="yes">
  <template slot="result-placeholder">

      ...

  </template>
</ws-search-result>

You can find details about the template placeholders in the detailed documentation for template placeholders.

Template for the WEBSALE product box (`incl_productbox.htm`)

To reload the product box, an additional template must be created and stored in the shop’s template directory (default: translation template directory). If the name of the template differs from incl_productbox.htm, the associated JavaScript script (see Search event dispatcher & forwarding of search queries) must be adjusted accordingly.

{WS-PRListFromLoadTplLink_data}
    {@WS-PRListFromLoadTplLink_data}
        {PR-LoadData($WS-PRListFromLoadTplLink_id$,1)}
            <WS-Ajax-wsProductWebComponent-~WS-PRListFromLoadTplLink_id~>

                ~WS-Fast_Include(Incl-ProductBoxCategory)~

            </WS-Ajax-wsProductWebComponent-~WS-PRListFromLoadTplLink_id~>
        {/PR-LoadData($WS-PRListFromLoadTplLink_id$,1)}
    {/@WS-PRListFromLoadTplLink_data}
{/WS-PRListFromLoadTplLink_data}

~WS-Fast_Include(Incl-ProductBoxCategory)~: This is the include area that loads the complete product box with all shop functions.

Incl-ProductBoxCategory usually comes from the file incl_fast_includes.htm, but can be named differently depending on the shop. Make sure to enter the correct include name. Inside the product box, the class wsProductBox-XX (replace XX with the product number) should be present so that these products, if already present, are not reloaded during sorting or filtering.

Filtering the products

Before filters are available in the frontend, the product data fields that can be used for filtering must be defined in the configuration of the search module. This configuration defines which filter types (e.g. checkboxes, sliders) can be used for specific fields.

Filter components

Example for the integration of the filter components:

<ws-filters>

  <ws-filter type="range" display-type="slider-fields" name="price" tag="~WS-Currency~" combined="true" show-labels="true"></ws-filter>

  <ws-filter type="checkbox" multiple="true" name="color" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="salesrank" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="rating" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="new_field" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="inventory" disable-style="disable-style"></ws-filter>
  <ws-filter type="checkbox" multiple="true" name="reduced_field" disable-style="disable-style"></ws-filter>

</ws-filters>

<ws-filter-chip btn-class="btn btn-secondary"></ws-filter-chip>

<ws-filter-reset>
    <button>Alle Filter entfernen</button>
</ws-filter-reset>

The filter components work dynamically and are rendered based on the configuration of the search module. If the user should be able to toggle a filter between Include (eq) and Exclude (neq), the ws-filter-toggle component can additionally be included before the respective filter:

<ws-filter-toggle name="color" label-on="Enthalten" label-off="Nicht enthalten"></ws-filter-toggle>
<ws-filter type="checkbox" multiple="true" name="color" disable-style="disable-style"></ws-filter>

You can find more details about usage and configuration in the detailed documentation:

JavaScript for rendering the filters

As of ws-search-component-1.9.1.js, this functionality is included natively in the WebComponents: filters are automatically set from the URL parameters and the category path when the page is loaded (see Automatic filter initialization). The following script is only required for older bundle versions.

When loading the products or after filtering, the active filters are passed to the WebComponents to display the correct filter values.

<script>
    document.addEventListener('DOMContentLoaded', () => {
      const url = new URL(window.location.href);
      const searchParams = new URLSearchParams(url.search);

      // Read category filter
      const categoryFilter = url.pathname.slice(1).replace(/\//g, '%2f');

      // Read active filters
      const appliedFilters = {};
      for (const [key, value] of searchParams.entries()) {
          if (key.startsWith('filter_eq[')) {
              const filterKey = key.slice(10, -1); // Extract the key inside filter_eq[]
              appliedFilters[filterKey] = appliedFilters[filterKey] || [];
              appliedFilters[filterKey].push({
              op_type: 'eq',
              value: [value],
              field: filterKey
              });
          }
      }

      // Dispatch event for wsSearchBox.js
      if (Object.keys(appliedFilters).length > 0) {
          const filterUpdateEvent = new CustomEvent('filterUpdate', {
              detail: {
                  applied_filters: appliedFilters,
                  category_filter: categoryFilter
              },
              bubbles: true,
              composed: true
          });
          document.dispatchEvent(filterUpdateEvent);
      }
    });
</script>

Sorting the products

The sorting is controlled via the <ws-sort-box> component:

<ws-sort-box></ws-sort-box>

You can find more details about the component in the detailed documentation for ws-sort-box.

Pagination / paging of the products

Pagination enables users to control the result page by selecting the number of products displayed per page and navigating between pages. This is done through a combination of several components for the result display, page size, and paging function. Example for the integration of the pagination components:

<ws-page-size-selector type="dropdown" mode="select" default="16" options='[16, 32, 48, 64, 80]'></ws-page-size-selector>

<ws-pagination max-pages="5">
  <button slot="prev"><</button>
  <button slot="current" style="font-weight: bold;"></button>
  <button slot="standard"></button>
  <button slot="next">></button>
</ws-pagination>

You can find more details about usage and configuration in the detailed documentation:

WS-Search

Setup

Integration into templates (Storefront)

Web components – Template placeholders

Web components – UI components

Scenario: search & search result page already integrated

Already existing components

Adjustments for the category page (`ws_category.htm`)

Extension of the existing communication component

Scenario: no existing search integration

Provision of the required resources

WEBSALE JavaScript library

JavaScript bundle

Communication component

Search event dispatcher for filter & sort

Integration of the products

Using the ws-search-result component

Template placeholder for the product box

Template for the WEBSALE product box (`incl_productbox.htm`)

Filtering the products

Filter components

JavaScript for rendering the filters

Sorting the products

​Scenario: search & search result page already integrated

​Already existing components

​Adjustments for the category page (ws_category.htm)

​Extension of the existing communication component

​Scenario: no existing search integration

​Provision of the required resources

​WEBSALE JavaScript library

​JavaScript bundle

​Communication component

​Inclusion of the search box component

​Search event dispatcher for filter & sort

​Integration of the products

​Using the ws-search-result component

​Template placeholder for the product box

​Template for the WEBSALE product box (incl_productbox.htm)

​Filtering the products

​Filter components

​JavaScript for rendering the filters

​Sorting the products

​Pagination / paging of the products

Scenario: search & search result page already integrated

Already existing components

Adjustments for the category page (`ws_category.htm`)

Extension of the existing communication component

Scenario: no existing search integration

Provision of the required resources

WEBSALE JavaScript library

JavaScript bundle

Communication component

Inclusion of the search box component

Search event dispatcher for filter & sort

Integration of the products

Using the ws-search-result component

Template placeholder for the product box

Template for the WEBSALE product box (`incl_productbox.htm`)

Filtering the products

Filter components

JavaScript for rendering the filters

Sorting the products

Pagination / paging of the products