jQuery Plugin Guide

The open source jQuery Plugin for Site Search can help you add existing functionality to your search experience, beyond what the standard implementations are able to accomplish.

This plugin takes the place of the Site Search JavaScript snippet.

After downloading the appropriate the jQuery files, you have three new scripts that you can add to the <head></head> tags of your website:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
<script type="text/javascript" src="jquery.swiftype.search.js"></script>

This provides you with...

jQuery
Site Search jQuery plugin.

A minimal search experience will look - at the absolute least - like below:

<!DOCTYPE html>
<html>
  <head>
    <title>The Most Minimal Seeking</title>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
    <script type="text/javascript" src="jquery.swiftype.search.js"></script>
  </head>
  <body>
    <form>
      <input type="text" placeholder="Search" id="st-search-input" />
    </form>
    <div id="st-results-container"></div>
  </body>
</html>

The jQuery plugin adds great substance, allowing you to script deeper interactions.

Add minimal jQuery to generate a default result set:

$('#st-search-input').swiftypeSearch({
  resultContainingElement: '#st-results-container', // Points to our results content division element.
  engineKey: 'swiftype-example-api' // Our Site Search Engine's unique key. Use your own!
});

Within our minimalist HTML template, it would look like this:

<html>
  <head>
    <title>The Most Minimal Seeking</title>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
    <script type="text/javascript" src="jquery.swiftype.search.js"></script>
    <script type='text/javascript'>
      $(function() {
        $('#st-search-input').swiftypeSearch({
          resultContainingElement: '#st-results-container',
          engineKey: 'swiftype-example-api'
        });
      });
    </script>
  </head>
  <body>
    <form>
      <input type="text" placeholder="Search" id="st-search-input" />
    </form>
    <div id="st-results-container"></div>
  </body>
</html>

The jQuery will call to the Engine you specify via the API to complete search requests.

The Search API Reference can be used to see the depths of your options.

When you find custom search parameters that feel right, you can extend your jQuery:

<script type='text/javascript'>
  $(function() {
    $('#st-search-input').swiftypeSearch({
      resultContainingElement: '#st-results-container',
      fetchFields: {'books': ['url']}, // Fetch the URL field as a raw field.
      engineKey: 'swiftype-example-api'
      highlightFields: {'books': {'title': {'size': 100, 'fallback': true }, 'genre': {'size': 60, 'fallback': true }}} // Fetch the title and genre fields as sanitized highlights.
    });
  });
</script>

This changes the results that you receive.

The second dimension within the plugin is styling these results.

Consider our extended jQuery example above. What if we want to use the genre field as part of our result design? We would do two things...

1: Apply a custom rendering function:

  var customRenderFunction = function(document_type, item) {
    var out = '<a href="' + item['url'] + '" class="st-search-result-link">' + item.highlight['title'] + '</a>';
    return out.concat('<p class="genre">' + item.highlight['genre'] + '</p>');
  };

2: Tell the jQuery plugin we are using custom styling...

<script type='text/javascript'>
  $(function() {
    $('#st-search-input').swiftypeSearch({
      renderFunction: customRenderFunction, // Use our custom function.
      fetchFields: {'books': ['url']}, // Fetch the URL field as a raw field.
      engineKey: 'swiftype-example-api'
      highlightFields: {'books': {'title': {'size': 100, 'fallback': true }, 'genre': {'size': 60, 'fallback': true }}} // Fetch the title and genre fields as sanitized highlights.
    });
  });
</script>

We will extend further, but instead of focusing on search we will look towards autocomplete.

Site Search users love customizing autocomplete.

Autocomplete looks for results based on a small sub-set of a query.

A user typing for chee will see results for cheese before finishing the word.

Autocomplete is a separate plugin.

As before, if this is our very minimal starting point:

<!DOCTYPE html>
<html>
  <head>
    <title>The Most Minimal Seeking</title>
    <script type="text/javascript" src="jquery.swiftype.autocomplete.js"></script>
  </head>
  <body>
    <form>
      <input type="text" placeholder="Search" id="st-search-input" />
    </form>
    <div id="st-results-container"></div>
  </body>
</html>

Our jQuery function calls a different function: swiftype instead of swiftypeSearch...

$('#st-search-input').swiftype({
  engineKey: 'swiftype-example-api'
});

It can be extended:

$('#st-search-input').swiftype({
  fetchFields: {'books': ['url']}, // Fetch the URL field as a raw field.
  engineKey: 'swiftype-example-api'
  highlightFields: {'books': {'title': {'size': 100, 'fallback': true }, 'genre': {'size': 60, 'fallback': true }}} // Fetch the title and genre fields as sanitized highlights.
});

... And can also apply a custom rendering function:

var customRenderFunction = function(document_type, item) {
  var out = '<a href="' + item['url'] + '" class="st-search-result-link">' + item.highlight['title'] + '</a>';
  return out.concat('<p class="genre">' + item.highlight['genre'] + '</p>');
};

Both the autocomplete and search jQuery plugin repositories provide a default stylesheet.

It shows the styling parameters that you can adjust to build your own style.

Stuck? Looking for help? Contact support or check out the Site Search community forum!

Site Search

Guides

Site Search API

API Reference

API Clients

Plugins

Resources

jQuery Plugin Guide