Theme Modifications for JSv2 / OS2 (Dawn)

Smart Search

The Smart Search integration hooks into your site’s existing search field to provide Klevu-driven quick search suggestions as your customers type, as well as adding a new search results page powered by our JavaScript library. Note that we do not offer an option to preserve your Shopify layout for search results at this time.

The Klevu app attempts to make the following changes automatically when enabling Smart Search via the Settings page. If you are installing Klevu on an unpublished theme, or encounter any errors during installation, you can follow the below instructions to ensure all the templates in your theme have been updated accordingly.

Search Results Landing Page

Create the Page Template

First create the SRLP template by clicking Add a new template under the Templates heading, with the following details

Add the following code to this template

<div class="page-width" 
{{ page.title }}
 <div class="klevuLanding"</div> </div>

Create the Search Results Page

Under Online Store > Pages, create a new page with the title “Search Results” using the Theme template you just created (klevu-search-results)

The content of this page should be empty, and the page should be visible.

Template Changes

Create the Klevu Snippets Files

We need to create two new templates under Snippets > Add a new snippet.

The first template we create should be called klevu-add-to-cart.liquid and contain the content found here: snippets/klevu-add-to-cart.liquid
This file will ensure that the JavaScript functionality required for Add To Cart buttons in your search results works as expected.
You should not need to make any changes to the content of this template.

Then we create the klevu-quick-search-theme.liquid file using the content here: sections/klevu-quick-search-theme.liquid
This file will attach Klevu functionality to the quick search input, and render output of the search results landing page created earlier.
You will need to replace some values in this file to connect to your Klevu account correctly.

• First, replace the options.search.url value with the APIv2 Cloud Search URL found in your KMC account on the Store Info page.
• Second, replace all references to “your Klevu JS API Key” (klevu-1234567890 in the boilerplate code) with the JS API Key value found in your KMC account on the Store Info page.
• Finally, if you need to make any customisations to your quick search or search results page behaviour, this should be included in this file.
  A reference to some common changes can be found in this guide.

Update Your Theme Files

Within your overall theme file, we need to inject both the Klevu JS Library and include the templates created above. In Layout > theme.liquid, add the following code immediately before the closing tag (included for reference)

<script src="//js.klevu.com/core/v2/klevu.js"</script>
    
    {% include 'klevu-add-to-cart' %}
    {% include 'klevu-quick-search-theme' %}
    

Additional Actions

Disable Native Quick Search Autocomplete

Depending on which theme you are using, you may already be outputting search suggestions in the quick search input.
Different themes will control this functionality in different ways, and your developers should be able to help you disable this either through configuration settings or template changes.

For the native Shopify Online Store 2.0 theme (Dawn), the easiest way to disable these suggestions is via the Customize option for your Current theme (under Online Store > Themes).
This will take you to the visual editor, where you should select the Header section and then deselect the “Enable product suggestions” option under Theme Settings

Smart Category Merchandising - Klevu Theme

When using Klevu Theme for the Smart Category Merchandising integration, the native Shopify collection page is replaced by our JavaScript-powered template, which injects the HTML and CSS required to display relevant products and filters to your customers.

The Klevu app attempts to make the following changes automatically when enabling Smart Category Merchandising via the Settings page, and selecting the “Use Klevu theme” option. If you are installing Klevu on an unpublished theme, or encounter any errors during installation, you can follow the below instructions to ensure all the templates in your theme have been updated accordingly.

Template Changes

Create the Klevu Snippets Files

We need to create two new templates under Snippets > Add a new snippet.

The first template we create should be called klevu-add-to-cart.liquid and contain the content found here: snippets/klevu-add-to-cart.liquid
This file will ensure that the JavaScript functionality required for Add To Cart buttons in your product cards works as expected.
You should not need to make any changes to the content of this template.

Then we create the klevu-catnav-theme.liquid file using the content here: snippets/klevu-catnav-theme.liquid
This file will include the JavaScript file (hosted by Klevu) responsible for rendering the collection page template, as well as defining the current category name for use in analytics.
You should not need to make any changes to the content of this template.

Create the Klevu Section File

To support the Online Store 2.0 rendering, we need to create a new section template to be included in the collection.json layout. We do this under Sections > Add a new section.

Create a new section called klevu-collection-theme.liquid containing the code found here: sections/klevu-collection-theme.liquid
This file contains a single, empty div element into which the Klevu JavaScript will inject content, as well as some additional schema markup used by Shopify to integrate the section with its visual theme customisation functionality.
You should not need to make any changes to the content of this file.

Update Your Theme Files

Within your overall theme file, we need to inject both the Klevu JS Library and include the snippet templates created above. In Layout > theme.liquid, add the following

<script src="//js.klevu.com/core/v2/klevu.js"</script>
    
    {% include 'klevu-add-to-cart' %}
    {% include 'klevu-catnav-theme' %}
    

templates/collection.json

Insert the Klevu Collection Section

The Templates > collection.json file contains details of all sections which are included in your category pages (and, therefore, can also be manipulated via the visual theme customisation tool). You will find two top levels sections in this file - sections, which contains definitions for all blocks (including settings changed in the customiser), and order, which defines the order in which the sections are output (which may be changed using the customiser’s drag-and-drop interface).

We need to add our new section to the end of the sections array, and ensure it is present in the order array, as per the below example.

Note, here, that the type value matches the name of the new section template we created above

{
  "sections": {
    /* Existing sections removed for illustration */
    "klevu-collection-theme": {
      "type": "klevu-collection-theme",
      "settings": {
      }
    }
  },
  "order": [
    /* Existing section keys removed for illustration */
    "klevu-collection-theme"
  ]
}

Disable the Existing Product Grid

We also need to disable the existing product grid output, otherwise both native Shopify and Klevu powered product output will be visible.

When you have identified the product grid section in Templates > collection.json, add the line "disabled": true. This will prevent Shopify from rendering the section’s output. 

If the line "disabled": false is already present in the file, simply change false to true

{
  "sections": {
    "banner": {
      "type": "main-collection-banner",
      "settings": {
      }
    },
    "product-grid": {
      "type": "main-collection-product-grid",
      /* Start Klevu change */
      "disabled": true,
      /* End Klevu change */
      "settings": {
      }
    },
    "klevu-collection-theme": {
      "type": "klevu-collection-theme",
      "settings": {
      }
    }
  },
  "order": [
    "banner",
    "product-grid",
    "klevu-collection-theme"
  ]
}

Alternative Method: Using the Visual Editor

You can also use the visual editor to toggle visibility of sections, accessed by clicking Customise next to the theme you wish to modify under Online Store > Themes.

You will need to select the Collection template you wish to modify from the dropdown at the top of the screen. This will usually be just “Default Collection”, in order to apply to all collection pages.

From here, you will see the sections from the JSON template available to drag-and-drop or toggle.
Disable the existing product grid section by hovering over its name and clicking the eye icon.

Then save your changes.

Smart Category Merchandising - Preserve Shopify Theme

Integrating Smart Category Merchandising using the Preserve Shopify Theme option retains the look and feel of your own theme. While there are no frontend display changes to implement, we need to include some code to ensure the necessary analytics calls are sent to Klevu.

The Klevu app attempts to make the following changes automatically when enabling Smart Category Merchandising via the Settings page, and selecting the “Preserve Shopify theme” option. If you are installing Klevu on an unpublished theme, or encounter any errors during installation, you can follow the below instructions to ensure all the templates in your theme have been updated accordingly.

Template Changes

Create the Klevu Snippets Files

We need to create four new templates under Snippets > Add a new snippet

The first template should be called klevu-pl-analytics.liquid and contain the content found here: snippets/klevu-pl-analytics.liquid
This file contains analytics functions and the necessary JSv2 power-up calls to initiate tracking functionality.
You will need to replace some values in this file to connect to your Klevu account correctly

• First, replace all references to “your Klevu JS API Key” (klevu-1234567890 in the boilerplate code) with the JS API Key value found in your KMC account on the Store Info page.
• Second, check that the Analytics URL value in your KMC account (on the Store Info page) is one of stats.klevu.com or stats.ksearchnet.com. If it is not, please replace the analytics and analyticsCat domains with the value in KMC

Next create klevu-pl-collection.liquid using the code here: snippets/klevu-pl-collection.liquid
This template is store and send data about visited categories.
You should not need to make any changes to the content of this template.

Create klevu-pl-collection-product.liquid from the following snippet: snippets/klevu-pl-collection-product.liquid
This short JavaScript code is injected to each product card, and allows us to track which products were viewed on a page.
You should not need to make any changes to the content of this template.

Finally, create klevu-pl-product.liquid with the content here: snippets/klevu-pl-product.liquid
This snippet will be injected into a product display page in order to track product clicks.
You should not need to make any changes to the content of this template.

Create the Klevu Section Files

To support the Online Store 2.0 rendering, we need to create a new section template to be included in the collection.json layout. We do this under Sections > Add a new section.

Create a new section called klevu-collection-pl.liquid containing the code found here: sections/klevu-collection-pl.liquid
This section acts as a container to output category page analytics snippets (created above), as well as some additional schema markup used by Shopify to integrate the section with its visual theme customisation functionality.
You should not need to make any changes to the content of this file.

Next, create another section at klevu-product-pl.liquid using the code at sections/klevu-product-pl.liquid
This section acts as a container to output product page analytics snippets (created above), as well as some additional schema markup used by Shopify to integrate the section with its visual theme customisation functionality.
You should not need to make any changes to the content of this file.

Update Your Theme Files

Within your overall theme file, we need to inject the Klevu JS library. Add the following snippet within the section of your code.

<script src="//js.klevu.com/core/v2/klevu.js"</script>

Insert the Klevu Collection Section

The Templates > collection.json file contains details of all sections which are included in your category pages (and, therefore, can also be manipulated via the visual theme customisation tool). You will find two top levels sections in this file - sections, which contains definitions for all blocks (including settings changed in the customiser), and order, which defines the order in which the sections are output (which may be changed using the customiser’s drag-and-drop interface).

We need to add our new section to the end of the sections array, and ensure it is present in the order array, as per the below example.

Note, here, that the type value matches the name of the new section template we created above.

{
  "sections": {
    /* Existing sections removed for illustration */
    "klevu-collection-pl": {
      "type": "klevu-collection-pl",
      "settings": {
      }
    }
  },
  "order": [
    /* Existing section keys removed for illustration */
    "klevu-collection-pl"
  ]
}

Insert the Klevu Product Section

As above, the Templates > product.json file contains details of all sections included in your product page.
We need to add our new section to the end of the sections array, and ensure it is present in the order array, as below.

{
  "sections": {
    /* Existing sections removed for illustration */
    "klevu-product-pl": {
      "type": "klevu-product-pl",
      "settings": {
      }
    }
  },
  "order": [
    /* Existing section keys removed for illustration */
    "klevu-product-pl"
  ]
}

Update the Product Card Snippet

Finally, we need to add a snippet to the file(s) responsible for rendering product cards in your category page.
Different themes use different names for these files, and there may be more than one responsible depending on the different layouts available in your theme. You can usually recognise these files when scanning the entries in the Snippets section, and looking for names containing the words “product” and “card”. Some examples used by Shopify themselves include

• Snippets > card-product.liquid
• Snippets > product-card.liquid
• Snippets > product-card-grid.liquid
• Snippets > product-card-list.liquid

First, open Sections > collection.json and find the section which renders a product list.
In Dawn, for example, you may see

{
  "sections": {
  /* Code omitted */
    "product-grid": {
      "type": "main-collection-product-grid",
      "settings": {
      }
    }
  },
  "order": [
  /* Code omitted */
    "product-grid"
  ]
}

Looking at the type tells us that we need Sections > main-collection-product-grid.liquid, so we open that file.

When you have your product collection template, locate the section of code which loops over and outputs the individual products. You are looking for something similar to

{%- for product in collection.products -%}

    


        {% render 'card-product',
            card_product: product,
            /* Code omitted */
        %}
    

{%- endfor -%}

Finally, we open product card template itself and add the following lines at the end of the file

{% render 'klevu-pl-collection-product', product: card_product %}

Additional Actions

Enable Preserve Layout Service

In order to display products in the correct order, our backend services will periodically update your collection order. To do this, we need to be notified that your site’s collections should be managed in this manner.
When using the automated integration through our app, this service will be enabled or disabled automatically as applicable. If you are integrating manually, however, please contact our support team to make the required change.
For more information about this service, please see our guide here.

Smart Recommendations

The Smart Recommendations integration updates your theme to allow rendering of Klevu-powered recommendations banners configured in the Merchant Center. Note that the following changes will not output any content to your site until you embed one or more HTML snippets (provided within the KMC) into your site. These snippets can be dropped into any template, and will not render output unless the steps below are in place.

The Klevu app attempts to make the following changes automatically when enabling Smart Search via the Settings page. If you are installing Klevu on an unpublished theme, or encounter any errors during installation, you can follow the below instructions to ensure all the templates in your theme have been updated accordingly.

Template Changes

Create the Klevu Snippets Files

We need to create two new templates under Snippets > Add a new snippet.

The first template we create should be called klevu-add-to-cart.liquid and contain the content found here: snippets/klevu-add-to-cart.liquid
This file will ensure that the JavaScript functionality required for Add To Cart buttons in your search results works as expected.
You should not need to make any changes to the content of this template.

Next we create the klevu-metadata.liquid file using the content here: snippets/klevu-metadata.liquid
This file will output some JavaScript variables on different pages which are used to provide context when generating recommendations results.
You should not need to make any changes to the content of this template.

Finally, create the klevu-recommendations.liquid file from the content here: snippets/klevu-recommendations.liquid 

This file will power-up the recommendations module, which retrieves and renders your banners.

You will need to replace some values in this file

• Replace all references to “your Klevu JS API Key” (klevu-1234567890 in the boilerplate code) with the JS API Key value found in your KMC account on the Store Info page.

If you need to make any customisations to your quick search or search results page behaviour, this should be included in this file.

A reference to some common changes can be found in this guide.

Update Your Theme Files

layout/theme.liquid

Within your overall theme file, we need to inject both the Klevu JS Library and include the templates created above. In Layout > theme.liquid, add the following code immediately before the closing tag (included for reference)

    
    {% include 'klevu-add-to-cart' %}
    {% include 'klevu-metadata' %}
    {% include 'klevu-recommendations' %}
    

Additional Actions

Embed Your Recommendations Banners

First locate the embed code from KMC, which can be found under Recommendations > Recommendations and clicking on the “code” icon. This will provide an HTML snippet in the form

<div class="klevu-recs" id="ABC-123"</div>

<div class="klevu-recs" klevu-data-id="ABC-123"</div>