Search-As-You-Type (SAYT) Tutorial

The following instructions will take you through all the steps you will need to apply SAYT to your search input field.

For this tutorial we will be applying SAYT to a sample provided below.

Prerequisites

To perform this procedure, you’ll need:

An account at groupbycloud.com and have an endpoint that allows you to upload and query data
Your query data ready and uploaded to your endpoint
Administrative access to your Command Center
Command line to run curl (Terminal in Mac, Cygwin in Windows) commands to upload and query data

Note: Curl is installed by default in most linux environments and you can download a curl port for Windows here: https://curl.haxx.se/download.html

Rendering Product Image in SAYT

In order for your product image to render under the product search, your data needs to have an image field. You can add an image field during data upload. For more information you can look at the Search Tutorial page for more information.

Step 1 - Starting Index.html

The following is the index.html that we will start with in this tutorial. This html simply creates an input box that users can type their search terms into.

<html>
<head>
    <link rel="stylesheet"
          href="http://code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css" />
    <link rel="stylesheet" href="css/demo.css" />
</head>

<body>
<div>
    <div>
        <!-- Search Form -->
        <form id="form" name="form" action="#">
            Search:&nbsp;
            <!-- query -->
            <input type="text" id="query" name="query">
            <!-- refinements -->
            <input type="hidden" id="refinements" name="refinements">
        </form>
    </div>
</div>

<script src="js/jquery-1.11.1.min.js"></script>
<script src="js/jquery-ui.min.js"></script>

</body>
</html>

Step 2 - Test your SAYT Service

You can test your SAYT web service by sending the following API request. The following request will hit the search endpoint and return search terms and navigation matches but no product matches.

For more information about the response format see the SAYT API documentation.

Send requests directly from the browser (CORS must be enabled)

$$.env

1 variable not set

customerid

Step 3 - Adding dependencies

The SAYT Widget depends on the following files, which can be added as shown below

sayt.js, which is the SAYT widget that processes all the search results.
```
<script src="/js/sayt.js"></script>
```
autcompleteTemplate.dust, which is used to render the results, can be downloaded here: autocompleteTemplate.dust. For a pre-compiled version of the autocomplete.dust, you can download the following file: autocompleteTemplate.js. For the purposes of this tutorial, we will be using the precompiled template. You can find more information about using the dust template file on the SAYT API page.
```
<script src="/js/autocompleteTemplate.js"></script>
```

In this tutorial, we will not have a collections input. We will input the collection directly into the sayt.js.

Step 4 - Linking SAYT Widget to your search field

Our index.html has one input fields that SAYT can operate on. This field will be for text input and displaying the search suggestions. As mentioned above, the collections field will be directly passed into the sayt.js through the following script.

Replace the <collection name> with the name of the collection which you wish to query against and the <default image> with the image you wish to appear in the product search if an image is not available.To tie the SAYT Widget to an input field, insert the following sample script block at the bottom of your index.html.

<script>
    $('#query').sayt({
        subdomain: '--customerId--',
        collection: '<collection name>',
        defaultImage: 'img/default.png',
        selectSearchTerm: function (data) {
            $('#query').val(data.value);
            $('#form').submit();
        },
        selectNavigation: function (data) {
            $('#query').val('');
            $('#refinements').val(
                    $('#refinements').val() + '~'
                    + data.category + '='
                    + data.value);
            $('#form').submit();
        },
        selectProduct: function (data) {
            // do product search here
        }
        ,
        autocompleteTemplate: 'at',
    });
</script>

You should now have a working version of SAYT.

Step 5 - Customizing SAYT

Our current SAYT options and default parameters look like the following.

    // SAYT Options
    subdomain: '--customerId--',

    // Search Params - Common
    collection: '',

    // Search Params - Autocomplete
    numSearchTerms: 5,
    numNavigations: 5,
    sortAlphabetically: false,

    // Search Params - Product
    area: 'Production',
    numProducts: 4,
    shouldSearchSuggestionFirst: true,
    hideNoProductsMessage: false,
    defaultImage: '',

    // Template Options
    defaultImage: '',
    autocompleteTemplate: 'autocompleteTemplate',
    productTemplate: 'productTemplate',
    delay: 250,

    // jQuery Autocomplete Options
    minLength: 3,

These values can be overridden from the index.html. When you call sayt.js you are able to pass in values of any of the above options. In our example in Step 4, we override a few of the values in sayt.js, such as subdomain and autocompleteTemplate. In a similar way, all the default parameters above can be overridden from the index.html to suit your website. For a list of all the options and their description, you can look at the SAYT API page.

Step 6 - Customizing the Dust Template

The autocomplete template and product template are responsible for rendering the search, product and navigation results in the SAYT widget. So far in this tutorial we have been using a precompiled autocomplete and product template to render our results. This section will go over making changes to the dust template and compiling it.

The following sections go over the basics of dust templating and how you would change this template in order to match your SAYT search.

Basic Dust Overview

The following are the key concepts in dust templating. For more information about dust templating you can view a the dust tutorial here: Dust Tutorial.

A section is a Dust tag of the form {#names}...{/names}. It is the way you loop over data in Dust. What happens is the current context (more on context shortly) is set to the “names” part of your JSON data. If names is an array, the body wrapped by the section tag is executed for each element of the array. If the element is not an array, the body will just be executed once. If the “names” element does not exist or is empty, the body will be skipped.

The provided template uses sections to navigate through the SAYT get response and display the data in the autocomplete menu. You can alter the template to navigate to the section that your SAYT GET response is returning. You can use the interactive JSON webapp in step 2 to see what section your data is being returned in.

For more information about dust template you can look at the following website: Dust Template Overview.

In the following sections we will have look at the product and autocomplete template that we are currently using.

Product Template

The following is the current product template that we are using, which can be downloaded here: productTemplate.dust.

{#items}
	{@if cond="'{stats.productCount}' > 0"}
		<li class="ui-autocomplete-category sayt-product-content">Products</li>
	{/if}

	{#products}
		<li class="ui-menu-item sayt-product-content" data-ui-autocomplete-item='{"title":"{allMeta.name}", "type":"product"}'>
			<a class="sayt-product-anchor">

                {@if cond="'{allMeta.image}'"}
                    <img class="sayt-product-image" src="{allMeta.image}">
                {:else}
                    <img class="sayt-product-image" src="{defaultImage}">
                {/if}

                <span class="sayt-content sayt-product-title">{allMeta.name|s}</span>
                <span class="sayt-content">{title}</span>
			</a>
		</li>
	{/products}
{/items}

In this template, we are currently displaying the two items for each product search result, the image and the title. The base image section is passed in from the sayt.js as the result field in the return JSON. So for this template, all the values you wish to display must be under the result field in your return JSON. For example, the title of product for this template is located in the following location in the return JSON: result > products > title. Similarly the product image is located in the following location in the return JSON: result > products > allMeta > image. If no image is present in this location, the default image will be used, which you have specified in step 4.

Autocomplete Template

The following is the current product template that we are using, which can be downloaded here: autocompleteTemplate.dust.

{#items}
    {#searchTerms}
        <li class="ui-menu-item" data-ui-autocomplete-item='{"value":"{value}", "type":"searchTerm"}'>
            <a>
                <span class="sayt-content">{value}</span> <span class="sayt-additional">
                    {@if cond="'{additionalInfo.manufacturer}'.length"}
                        Brand:
                        {#additionalInfo.manufacturer}
                            <span class="sayt-hyperlink">{.}</span>{@sep} {/sep}
                        {/additionalInfo.manufacturer}
                    {/if}
                </span>
            </a>
        </li>
    {/searchTerms}

    {#navigations}
        {#department}
            <li class="ui-autocomplete-category">Department</li>
            {#values}
                <li class="ui-menu-item" data-ui-autocomplete-item='{"value":"{.}", "type":"navigation", "category":"{name}"}'>
                    <a>
                        <span class="sayt-content">{.}</span>
                    </a>
                </li>
            {/values}
        {/department}

        {#manufacturer}
            <li class="ui-autocomplete-category">Manufacturer</li>
            {#values}
                <li class="ui-menu-item" data-ui-autocomplete-item='{"value":"{.}", "type":"navigation", "category":"{name}"}'>
                    <a>
                        <span class="sayt-content">{.}</span>
                    </a>
                </li>
            {/values}
        {/manufacturer}

        {#modelNumber}
            <li class="ui-austocomplete-category">Model #</li>
            {#values}
                <li class="ui-menu-item" data-ui-autocomplete-item='{"value":"{.}", "type":"navigation", "category":"{name}"}'>
                    <a>
                        <span class="sayt-content">{.}</span>
                    </a>
                </li>
            {/values}
        {/modelNumber}
    {/navigations}
{/items}

The autocomplete template has two main sections, searchTerm and navigation. Similar to the product template, the items section is passed in as the result field in the return JSON from the sayt.js. The navigation section has three sections, department, manufacturer and modelNumber. The order in which these sections render are the same as the order in which they are declared. Using a similar structure as one of the sections under navigation, you can add more navigations fields.

Dust Compiler

After you have finished modifying the dust template, you can use a dust compiler to compile your .dust to a .js file. After you have compiled your .dust template into a .js file replace the existing compiled template in your webapp, and view your changes.

You can use the dust compiler here to compile your dust template, as well as verify the output. Put your data and template in the respective boxes on the page, and then when you are satisfied with the output, click Dev Mode (top-right hand corner in the “Dust Template” box) to open up an additional box where you can obtain the compiled dust.