Skip to main content
The WEBSALE | search module not only enables classic product search but can also be used for filtering and sorting on category pages. This allows customers to 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 of the required components are already present and only targeted adjustments to the category templates are required.
  • If no WEBSALE search is used (for example because an external service 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

Components already present

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:
  • JavaScript bundle (ws-search-component-<version identifier>.js)
  • Communication component (ws-search)
  • Search input field with optional suggest function (ws-search-box)
  • Template helper (ws-search-template-helper-<version identifier>.js) with the wsConfig object
  • AJAX view for the product boxes

Adjustments for the category page (views/category.htm)

For the category template views/category.htm, only the following additional adjustments are then required:
  • Inclusion of the ws-search-result component
  • Template placeholder for the product box (<template slot="result-placeholder">)
  • 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

Extending the existing communication component

The <ws-search> component may only occur once in the template. Since it has already been included for the search & search result page, you only need to add the category attribute with the ID of the current category for the category page.

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, all required components for the filter and sort functions on category pages must be explicitly included in the category template (views/category.htm). The following guide describes the necessary adjustments to correctly integrate filtering and sorting via the WEBSALE search module.

Providing the required resources

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

JavaScript bundle

WEBSALE provides the JavaScript bundle ws-search-component-<version identifier>.js. It is required for the filter and sort components. Include the bundle via <script>:
You can find the current version under JavaScript bundles. If you want to make individual adjustments to the filter or sort logic, download the file via the same link and adapt it.

Communication component

In addition to the JavaScript bundle, the ws-search component is required. It is provided by WEBSALE and handles the communication between the frontend, the backend, and the included WebComponents. This component may only occur once per template. The category attribute contains the ID of the current category.
You can find more details about the communication component in the detailed documentation for the ws-search component.

Including the search box component

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

Template helper

As on the search result page, the template helper ws-search-template-helper-<version identifier>.js loads the product boxes as of version 1.1.x. Create the wsConfig object before including it:
The settings are described under Template helper and loading the product boxes.

Integrating 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.
You can find details on how this component works in the detailed documentation for ws-search-result.

Template placeholder for the product box

To prevent layout shifts while the product boxes load, you can specify a <template> within ws-search-result. It is displayed while the product box is loading. To define the template for the placeholders, result-placeholder must be specified for the slot:
You can find details on the template placeholders in the detailed documentation for template placeholders.

AJAX view for the product boxes

The product boxes use the same AJAX view as on the search result page, in the reference template views/ajax/wsSearch.htm. Structure and parameters are described under AJAX view for the product boxes. On the category page as well, each product box must contain an element within its container wsProductWebComponent-<product ID> whose ID starts with wsProductBox-. If this element is missing, the template helper removes the container again as empty after loading and the product boxes disappear.

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, for example checkboxes or sliders, can be used for specific fields.

Filter components

Example for the integration of the filter components:
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:
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 natively included in the WebComponents: filters are set automatically from the URL parameters and the category path when the page loads (see Automatic filter initialization). The following script is only required for older bundle versions.
When the products are loaded or after filtering, the active filters are passed to the WebComponents so that the correct filter values are displayed.

Sorting the products

The sorting is controlled via the <ws-sort-box> component:
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:
You can find more details about usage and configuration in the detailed documentation: