Step 3 - Integrate Fredhopper Suggest in your website

This page explains how to integrate Fredhopper Suggest Search in your front-end

Introduction

The Suggest Query Server returns the suggestions as a JSON message - the lightweight exchange format for JavaScript.

Fredhopper delivers a sample Ajax module which is based on the popular JavaScript library Prototype. The source code of the module could be found at Tools & Downloads. Alternatively, e.g. if there are conflicts with other libraries, you can implement your custom Ajax module to use Fredhopper Suggest. There are various tutorials and open source implementations available online.

Fredhopper Ajax box

If the Suggest Query Server is not available or does not contain an index, the sample Fredhopper Ajax module will not show the the suggest drop down. For custom Ajax modules it is highly recommended to foresee this situation since it occurs e.g. during index updates.

To change the design of the generated HTML, you have to edit the templates.

The fredhopper.js reference implementation uses the following special fields by convention:

• searchterm: searchterm that is triggered by the suggestion
• secondId: second ID to which the suggestion links
• fhLocation: explicit FAS location (required for non-keyword or item links)
• image: image of the suggestion
• nrResults: number of items that the execution of this suggestion would lead to

Ensure to follow the field naming in your index if you want to use the fredhopper.js reference implementation, e.g. if you call the image field image_url the implementation will render the URL as text instead as an image.

If Suggest Query Server is running in a different folder than the Ajax box then you will have to specified in the third parameter 'suggest' which are script that translate the response, e.g.

var autocompleter = new Fredhopper.Autocompleter('search','searchupdate','http://localhost/my-suggest/json',

HTML Templates

The provided HTML templates are just a sample. You will most likely implement the Ajax box using your technology of choice directly connecting to the Fredhopper Suggest JSON API.

Suggest service uses the Prototype JS library. Template as a template engine. Each index file should have two template files associated with it - one for the group of suggestions and one for each suggestion entry in this group.
For example if you want to create templates for a new index file named "MyIndex.idx" then you need to create two files with the following content:

<textarea id="MyIndex_template" style="display: none;">

	<div class="suggest-header-div">
		<span class="suggest-header">#{indexTitle}</span>
	</div>

	<ul>
		#{suggestionItems}
	</ul>

</textarea>

<textarea id="MyIndex_item_template" style="display: none;">
	<li class="suggestoption" style="list-style-type: none;" >
		<a href="javascript: location.href=fasUrl + 'preview_query=fh_location%3D' + escape('#{fhLocation}')">
			<div class="someStyle">#{mlValue}</div>
		</a>
	</li>
</textarea>

Important notes

• The templates must be included in the page where the Autocompleter will be used.
  For example:

1. JSP - <jsp:include page="templates/my_index.tmpl.tmpl" />
2. PHP - <?php include("templates/my_index.tmpl.tmpl"); ?>
3. ...

• The templates should be in

  <textarea>

elements. This is the most safe way to include markup which should not be modified by the browser.

• The value of

  id

  attribute should follow the following convention:

1. for the whole group: the name of the index file without the extension + '_template'.
2. for the item: the name of the index file without the extension + '_template_item'.
   Note: if the name of the index file contains a space then this space should be replaced by an undescore character. E.g.: file name - 'My Index.idx', group template id - 'My_Index_template'.

Default templates

The Suggest service provides default templates which will be used in the cases when there are no custom provided.

Notes

• To be able to use the default templates you need to include them.
• The default templates are suitable for demos - just put the index file and see the result. If you need better looking autocomplete drop-down then you have to create custom templates.
• Index fields with name - 'searchterm', 'fhLocation' and 'secondId' have a special meaning in the default templates. They are always vizualized as links. To define which other field from the index file to be used as a title of the link you need to rename the special field to 'special_other'.
  Example: the index file contains special field 'secondId' and non-special fields 'author', 'price' and 'image'. To use 'author' as a link title you need to rename 'secondId' field to 'secondId_author'. This way the produced link will look like:
  <a href="openSecondId('#{secondId}')">#{author}</a>
  The values of all other fields ('price' and 'image') will be visualized one by line.
  Note: all fields which values ends with .jpg, .png or .gif will be visualized as images.

Security

Cross-site scripting is one of the major security vulnerabilities on websites. Fredhopper Suggest Search returns just JSON documents and is therefore safe regarding cross-site scripting. Fredhopper's Ajax box for Suggest Search doesn't write back any input entered by users.