Integrating FINDOLOGIC - WEBSALE Dokumentation

The shop’s internal search finds what the customer types. FINDOLOGIC finds what they mean: it forgives typos, recognizes related terms and moves the matching products to the top. A customer who enters “tshrit” gets T-shirts, and anyone searching for “iPad” gets iPads rather than charging cables.

WEBSALE V8s integrates three FINDOLOGIC functions directly:

Function	What it does
Search	replaces the internal search, with its own ranking and error tolerance
Suggest	shows suggestions for products, categories and brands while the user is still typing
Filter	refines the result list by category, manufacturer, price and attributes

When crawling the shop, search engines also follow the links of all filter options and their subsequent pages. This can greatly increase the number of pages retrieved. Discuss with the person responsible for SEO how to limit this, for example with the rel="nofollow" attribute on these links.

Prerequisites

Two accounts are required, and both sides have to contribute:

With whom	What
FINDOLOGIC	an account, which you request directly from them
WEBSALE	activation of the FINDOLOGIC search, the tracking interface and the Dataflow-Manager

If the search is used, the product data must be transferred to FINDOLOGIC regularly. This export runs via the Dataflow-Manager and is triggered by WEBSALE.

You currently cannot adjust the data feed to FINDOLOGIC yourself; WEBSALE takes care of this. Alternatively, the export can also be run from your merchandise management system.

Clarify beforehand

These questions should be discussed with FINDOLOGIC and with WEBSALE before anyone touches a template:

Which of the three functions are to be used?
Which data basis, which data source and which update interval are desired?
In which subshops should FINDOLOGIC operate?
Which filters and sort options should the result list offer? This is defined per subshop.
What are the address and the shopkey for the call from the shop?

You need the last two points in each of the following steps, and you can only get both from FINDOLOGIC.

Data transfer

By default, FINDOLOGIC receives only your shop’s product data, as the basis for all three functions. Special prerequisites apply to further data and must be clarified with both sides. This is done via a profile in the Dataflow-Manager, which you define together with WEBSALE. It determines which product field types and which individual details are transferred, for example price, brand and color, as well as the transfer interval. After the profile has been created, you receive an export address for the data feed as a CSV file. Enter this address in your FINDOLOGIC account under “Einstellungen > Import/Export” in the “CSV-URL” field. Once the export is in place, define the preconfiguration for filters and sort options with FINDOLOGIC.

Integrating the search

Step 1: Set up the fallback

If FINDOLOGIC fails, the customer should not be faced with an empty result list. The LiveCheck checks availability, and in an emergency the shop shows its own search results.

<ExternSystemLiveChecks>
   <+Entry>
      ID        = FindologicSearch
      URL       = https://...  (Adresse von FINDOLOGIC inklusive Shopkey)
      Type      = 2
      CheckMode = always
      Timeout   = 1000
   </+Entry>
</ExternSystemLiveChecks>

You receive the address for this check from FINDOLOGIC. It usually ends in alivetest.php and carries the shopkey as a parameter:

https://srv12.findologic.com/ps/ihr-shop.de/alivetest.php?shopkey=<Ihr Shopkey>

CheckMode = always checks again on every page request. This costs time, but is correct here: an outage remembered for the whole session would keep sending the customer to the internal search even when FINDOLOGIC has long since started responding again.

Reference: Section ExternSystemLiveChecks Guide: Integrating external content

Step 2: Adjust the search results page

The results are displayed on the template listed after Search in the <Templates> section of the shop.config. There, the area with the shop’s own search results is supplemented by an area with the external include. The shop’s own area then only appears when FINDOLOGIC cannot be reached.

{WS-ExternSystemLiveCheck(FindologicSearch)}

   <!-- Suchergebnisse von FINDOLOGIC -->
   ~WS-ExternInclude(https://srv12.findologic.com/ps/ihr-shop.de/index.php?Ctx=$WS-Ctx$&search_input=$WS-SearchEnc$&shopkey=<Ihr Shopkey>)~

{/WS-ExternSystemLiveCheck(FindologicSearch)}

{!WS-ExternSystemLiveCheck(FindologicSearch)}

   <!-- eigene Suchergebnisse, wenn FINDOLOGIC nicht erreichbar ist -->
   {@PR-Data}
      ~PR-Name~
   {/@PR-Data}

{/!WS-ExternSystemLiveCheck(FindologicSearch)}

The search term is passed into the address via WS-SearchEnc, i.e. in URL-encoded form. The unencoded term would result in an invalid address if it contains spaces or umlauts.

To prevent the internal search from doing additional work during normal operation, it can be deactivated. This is a separate step and is part of the changeover.

Reference: WS-ExternSystemLiveCheck() · WS-ExternInclude() · WS-SearchEnc Guide: Deactivating the internal WEBSALE search when using external search providers

Step 3: Design the result list

The design is not done in the shop but in the template manager of the FINDOLOGIC account. There you will find a shop-specific template named websale.tpl, which your FINDOLOGIC contact provides on request. It already includes:

filtering and sorting of the search results
selection of hits per page
pagination
display of the search term and the number of hits
the search results themselves

The real trick lies in the <div id="flResults"> area: you may use WEBSALE tags there. This means the product display in the shop and in the FINDOLOGIC result list can be identical.

<div id="flResults">
   {not_found message="Es wurden keine Produkte gefunden"}
   {foreach from=$RESULT item=ITEM}
      {literal}~DC-FP1_set({/literal}{$ITEM.ORDERNUMBER}{literal})~{PR-AdvData($DC-FP1$)}~PR-Name~{/PR-AdvData($DC-FP1$)}{/literal}
   {/foreach}
   <div class="clear"></div>
</div>

This is how the block works: FINDOLOGIC supplies the order number for each hit. It is placed in a free placeholder, and PR-AdvData() fetches the corresponding product data from the shop. Within this bracketing, all the usual product tags are then available.

The {literal} areas belong to FINDOLOGIC’s template language. They ensure that the WEBSALE tags are passed through unchanged instead of being interpreted as instructions themselves.

If you already use a FastInclude for the product display, it can be used here in the same way:

<div id="flResults">
   {not_found message="Es wurden keine Produkte gefunden"}
   {foreach from=$RESULT item=ITEM}
      {literal}~DC-FP1_set({/literal}{$ITEM.ORDERNUMBER}{literal})~{PR-AdvData($DC-FP1$)}~WS-Fast_Include(Incl-ProductList)~{/PR-AdvData($DC-FP1$)}{/literal}
   {/foreach}
   <div class="clear"></div>
</div>

This way, product tiles look the same in the category and in the result list, and a change takes effect in both places. Reference: DC-FP1…5 · DC-FP1…5_set() · PR-AdvData() · PR-Name · WS-Fast_Include()

Step 4: Apply the styling

The HTML elements in the FINDOLOGIC template already carry classes and IDs. Add these to your shop’s stylesheet and give them the desired properties.

Integrating the suggest function

The suggestions appear in a separate layer directly below the search input field as soon as FINDOLOGIC finds something for the letters entered. This is often the case after just a few characters.

Step 1: WEBSALE JavaScript library

Check whether the system library and the design component are included, and otherwise add them in the <head> area.

<head>
   ...
   <script type="text/javascript" src="/$WS/ws_sysdata/js/ws-system-1.8.3.js"></script>
   <script type="text/javascript" src="../ihr-verzeichnis/ws-design-1.8.3.js"></script>
   ...
</head>

Materials: WEBSALE JavaScript library

Step 2: jQuery components

File	Purpose
`jquery.autocomplete.js`	the suggest function itself, always required
`jquery.preload.js`	only required if the suggestions are to show preview images

Both files are available for download under “Materials”. Save them in your JavaScript directory and include them in the <head> area.

<head>
   ...
   <script type="text/javascript" src="../js/web/jquery.autocomplete.js"></script>
   <script type="text/javascript" src="../js/web/jquery.preload.js"></script>
   ...
</head>

Materials: jquery.autocomplete.js · jquery.preload.js

Step 3: Adjust the search input field

The usual QuickSearch form is used. Two things change:

Change	Why
`method="get"` instead of `method="post"`	the suggest function works with the address, not with submitted form data
`id="flAutocompleteInputText"` on the input field	this is how the script finds the field below which the layer appears

<form action="~FORM-QuickSearch~" method="get">

   <input name="~WS-Search_Input~" type="text" value="Ihr Suchbegriff" id="flAutocompleteInputText">
   <input type="submit" value="Suchen">

   <script type="text/javascript">autocompleteField = jQuery("#flAutocompleteInputText");</script>
   <script type="text/javascript" src="../js/web/findologic_suggest.js"></script>

</form>

The ID flAutocompleteInputText is mandatory and must not be renamed. Without it, no suggestion layer appears, and there is no error message.

The script findologic_suggest.js requires the two jQuery components from step 2. It must therefore be loaded after them. If it comes before them, the function has no effect.

Reference: FORM-QuickSearch · WS-Search_Input Materials: findologic_suggest.js

Step 4: Design the suggestion layer

findologic_suggest.js builds the layer itself. Its elements already carry classes to which you assign properties. Under “Materials” you will find a stylesheet with a selection of these classes. You can either place the file in the CSS directory or copy its content into the shop’s existing stylesheet. Materials: findologic_suggest.css

Overview of the process

For planning what happens in which order:

Contact FINDOLOGIC, order the functions and agree on the configuration.
Arrange the activations with WEBSALE and define the data export.
Select subshops and clarify the language-dependent points, for example the conversion of the character encoding and the relationship between field names and display names.
Build the search results page and configure hits per page, pagination and the filters.
Build the suggest function into all shop pages.
Adapt all display elements to the shop’s design.

Guide: Integrating external content
Guide: Deactivating the internal WEBSALE search when using external search providers
Guide: Search

​Prerequisites

​Clarify beforehand

​Data transfer

​Integrating the search

​Step 1: Set up the fallback

​Step 2: Adjust the search results page

​Step 3: Design the result list

​Step 4: Apply the styling

​Integrating the suggest function

​Step 1: WEBSALE JavaScript library

​Step 2: jQuery components

​Step 3: Adjust the search input field

​Step 4: Design the suggestion layer

​Overview of the process

​Related topics

Prerequisites

Clarify beforehand

Data transfer

Integrating the search

Step 1: Set up the fallback

Step 2: Adjust the search results page

Step 3: Design the result list

Step 4: Apply the styling

Integrating the suggest function

Step 1: WEBSALE JavaScript library

Step 2: jQuery components

Step 3: Adjust the search input field

Step 4: Design the suggestion layer

Overview of the process

Related topics