The Suggestions Plugin can be used to implement a standardized version of the Tweakwise suggestions in your platform.

🔗 View live demo of Suggestions

Installation

Make sure you have followed the Installation guide.

Initialization

The Suggestions plugin needs to be initialized manually. To do this, copy the following snippet into your HTML.

<script>
  window.addEventListener("twn.suggestions.ready", function () {
    window.tweakwiseSuggestions({
      input: "INPUT",
      instancekey: "INSTANCEKEY",
      cid: "CID"
    });
  });
</script>

The only thing that is left is to replace INPUT, INSTANCEKEY and CID with the correct values.

The INPUT should be replaced with a valid CSS selector leading to an existing search input on the page. This input will be used as the source for the suggestions.

The INSTANCEKEY should be replaced with your own instance key. You can find it in Tweakwise on the Connectivity > Endpoints page.

The CID should be replaced with the root category ID of the search results.

📘

If you have multiple input fields where you want to use the Suggestions (for example one for mobile and one for desktop), you can add this script multiple times. Once for each input field you want to use.

Search phrase suggestions

The Suggestions plugin supports search phrase suggestions out-of-the-box. However, when using search phrases grouped by category additional configuration may be required. When the user selects a search phrase with a category, the category id will be added to the query string of the target URL:

/search?q=searchphrase&tn_cid=100012

By default tn_cid is used to add the category id to the URL. However, it is possible to override this value:

<script>
  window.addEventListener("twn.suggestions.ready", function () {
    window.tweakwiseSuggestions({
      input: "INPUT",
      instancekey: "INSTANCEKEY",
      cid: "CID",
      
      searchPhrases: {
        categoryKey: "tn_cid" // <-- Configure the URL key here
      }
    });
  });
</script>

Category & facet suggestions

Category and facet suggestions are not displayed out-of-the-box. Additional configuration is required. For both types a function should be implemented that navigates to the correct page when the user selects these suggestions:

<script>
  window.addEventListener("twn.suggestions.ready", function () {
    window.tweakwiseSuggestions({
      input: "INPUT",
      //..
      categories: {
        handle(event) {
          var suggestion = event.data;
          
          // Handle category suggestion here...
        }
      },
      
      facetFilters: {
        handle(event) {
          var suggestion = event.data;
          // Handle facet suggestion here...
        }
      }
    });
  });
</script>

For detailed examples, see Category suggestion navigation.

Note: if the handle option is not defined, the corresponding type of suggestions will not be shown.

Product suggestions

The Suggestions plugin supports product suggestions out-of-the-box. For this type of suggestions no additional configuration is needed.

Connecting to search results

To allow seamless connection with search results, surround the input with a form and submit button:

<form action="/search">
  <input name="q" placeholder="What are you looking for?" />
  <button type="submit">Search</button>
</form>

Suggestions JS will process the form submit and excute the searchPhrases.handle callback.
This way you will be in control of handling the way to search:

<script>
  window.addEventListener("twn.suggestions.ready", function () {
    window.tweakwiseSuggestions({
      input: "INPUT",
      instancekey: "INSTANCEKEY",
      cid: "CID",      
      searchPhrases: {
        handle: function(e){
          // redirect to search page
          location.href = '/search#twn|?tn_q=' + e.data.match;
          // or if using manual listerpage initialization (https://docs.tweakwise.com/reference/plugin-studio-manual-init)
          listerPage.setQuery(e.data.match)
        }
      }
    });
  });
</script>

Redirects

The Suggestions plugin supports redirects out-of-the-box. The user will be redirected to the configured page if:

• the user selects a search phrase that is associated with a redirect.
• the user hits enter and
  • the input is surrounded by a form
  • the searchPhrases.handle callback is implemented
  • and the form is submitted using a searchterm associated with a redirec