Search & search result page

This documentation describes the integration and use of the search functions of the WEBSALE | search module in a WEBSALE online shop. It covers the setup of the search input field (with or without the suggest function), the display of search results, and the after-search navigation for filtering and sorting the results. This documentation describes the standard integration of the WEBSALE | search module, based on the common shop setup in which the search input field is available on every page of the shop. In most cases, the search input field is placed in the header of the shop so that the search function is available to the user at any time.

Global integration in all templates

In most cases, the search input field (ws-search-box) is integrated in the header of the shop so that the search can be reached from every page. For the search to work on all pages, certain components and scripts must be included in all templates on which the search input field is displayed. These ensure communication with the search backend and the processing of the search queries. If the components and scripts should not be included directly in every template, an include area can be created in the FastInclude file (incl_fast_includes.htm) and then referenced in the required templates. The required components and scripts are described in the following.

WEBSALE JavaScript library

The WEBSALE JavaScript library is required for the integration. It provides all relevant JavaScript modules for the search module as well as other standard shop functions. Depending on requirements, two variants of the library can be included:

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.

The WEBSALE JavaScript library is only needed once per template. If it is already included in the templates for other shop functions, no further integration is required.

JavaScript bundle

WEBSALE provides a JavaScript bundle with the name ws-search-component-<version identifier>.js via the WEBSALE JavaScript library. This bundle is also managed via the WEBSALE PageSpeed tool and is required for the integration and functionality of the search component. You can include the bundle directly in your templates, like all other JavaScript components provided by WEBSALE, by configuring it via the PageSpeed tool. If you would like to individualize or adjust the bundle, the file is available for download at the following URL:

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

This option enables you to make specific adjustments for your shop templates, for example changes to the behavior of the search or the filter logic.

Communication component

The communication component is required everywhere the search input field (ws-search-box) is used, but only once per page. It ensures that search queries are processed correctly and transmitted to the backend.

<ws-search url="https://<your-shopid>.search.websale.net/api" subshop="~WS-SubShopID~" page-size="24" keep-query="yes"></ws-search>

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

Search input field with optional suggest function

The search input field is included via the <ws-search-box> component. This component represents the frontend input field and can optionally be supplemented with a suggest function. Additionally, a button for submitting the search query can be integrated via the <ws-search-button> component.

<ws-search-box use-suggest="true">
    <input type="search" name="query" placeholder="Artikel suchen">
    <ws-search-button>
        <button type="button" title="Suche abschicken"></button>
    </ws-search-button>
</ws-search-box>

You can find more details about the use of the components in the detailed documentation for the ws-search-box and ws-search-button components.

Search event dispatcher & forwarding of search queries

The following script is required to correctly process search queries, provide search results globally in the shop, and forward new search queries to the search result page. It 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)}
		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>

The script has the following tasks:

Processing the search results (wsResultDispatcher.subscribe)
- Monitors the JSON response of the search module and outputs the received data in the console.
- Creates a list of product numbers and prepares them for an AJAX request to load the product boxes.
- When search results are available, ws_AJAXloadTemplatePOST() is executed to reload the product boxes.
AJAX methods for the product box request
- Provides empty functions for the AJAX events start, success, error, and failure.
- These can be overridden or extended with your own functions as needed.
Event listener for new search queries (wsPerformSearch event)
- Ensures that search queries are forwarded to the search result page.
- As soon as a new search query is started, the URL is adjusted accordingly and the user is forwarded to the result page.
Extracts search parameters from the URL (DOMContentLoaded event)
- Loads the current search parameters from the URL when the page is loaded.
- Prepares the parameters for further functions or filter mechanisms.

Integration on the search result page (`ws_search.htm`)

The default template for displaying the search result page is ws_search.htm.

Using the ws-search-result component

The <ws-search-result> component delivers the product list based on the entered search term, the selected filters, and sort options.

<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 section 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 search results

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. 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. You can find more details about usage and configuration in the detailed documentation:

Sorting the search results

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

<ws-sort-box use-api="true"></ws-sort-box>

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

Pagination / paging of the search results

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

Global integration in all templates

WEBSALE JavaScript library

JavaScript bundle

Communication component

Search input field with optional suggest function

Search event dispatcher & forwarding of search queries

Integration on the search result page (`ws_search.htm`)

Using the ws-search-result component

Template placeholder for the product box

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

Filtering the search results

Sorting the search results

​Global integration in all templates

​WEBSALE JavaScript library

​JavaScript bundle

​Communication component

​Search input field with optional suggest function

​Search event dispatcher & forwarding of search queries

​Integration on the search result page (ws_search.htm)

​Using the ws-search-result component

​Template placeholder for the product box

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

​Filtering the search results

​Sorting the search results

​Pagination / paging of the search results

Global integration in all templates

WEBSALE JavaScript library

JavaScript bundle

Communication component

Search input field with optional suggest function

Search event dispatcher & forwarding of search queries

Integration on the search result page (`ws_search.htm`)

Using the ws-search-result component

Template placeholder for the product box

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

Filtering the search results

Sorting the search results

Pagination / paging of the search results