search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Design and Customization

Once you have indexed your content into Site Search, the question then becomes: how will I build a great search experience? There are two key considerations: how do I want my search field to appear and how do I want my results to appear? The goal of this guide is to introduce you to the stylistic options available within Site Search.

You can go for out-of-the-box options to quickly get started. This includes using the Site Search search tab and the Site Search overlay. Or, you can fully customize your ideal search experience -- check out the search field within this documentation for an example of where you can take things. It is located at the top right of the page.

To begin, we will introduce the two aesthetic components of a typical search experience:

Next, we will look at how to use the Site Search dashboard to alter the Basic Appearance.

Finally, an introduction to deep, coded Custom Search Implementations.

Search Field

Some may call it the search bar, the search box, or the magical rectangle. The search field is the place in which a user will input their search queries. Your web browser has one, each search engine like Google or DuckDuckGo has one, and you will need one to provide search.

A basic installation of Site Search requires the Site Search JavaScript snippet. It can be installed within the <body></body> tags of your website:

<script type="text/javascript">
  (function(w,d,t,u,n,s,e){w['SwiftypeObject']=n;w[n]=w[n]||function(){
  (w[n].q=w[n].q||[]).push(arguments);};s=d.createElement(t);
  e=d.getElementsByTagName(t)[0];s.async=1;s.src=u;e.parentNode.insertBefore(s,e);
  })(window,document,'script','//s.swiftypecdn.com/install/v2/st.js','_st');

  _st('install','xxxxx-xxxxxx-xxxxxx','2.0.0');
</script>

You may be using search within your website already. If so, you already have a search field into which we will need to weave Site Search. Doing so requires that we add additional information into your HTML with which the Site Search JavaScript will interact.

The information we need to add is a class: st-default-search-input.

If you had a <form></form> containing an input tag within your search field, like so:

<form>
  <input type="text" />
</form>

You would then extend it to include the Site Search class:

<form>
  <input type="text" class="st-default-search-input" />
</form>

The JavaScript will then interact with this class and search requests within your search field will communicate with your Site Search Engine. We need look no further than the search experience within Swiftype.com for an example of a customized search field:

Site Search - Swiftype.com search, an example search field.
A customized search field from swiftype.com - it is slick, minimal, and has character.

To see it in action, click into the search field at the top right of this document.

If you do not have a search field, you can create your own. Or, Site Search has an out-of-the-box solution that you can use known as the Site Search search tab. If you select the tab during the installation flow, it will appear in the bottom right of each page that contains the Site Search JavaScript snippet once you activate search.

Site Search - The search tab.
A clean black tab at the bottom right hand corner of a page, magnified in a stylistic manner.

Results Container

The results container is the space where your search results appear. In some cases it appears over top of your website content as an overlay. In others, it appears in its own webpage or as a part of every page. Site Search can satisfy each of these choices.

The most popular method is the Site Search overlay. Your website dims and the overlay appears on top of it. You can apply custom styling, but the overlay exists "separate" from your own pages. When you combine the overlay with the Site Search search tab, you need only install the JavaScript snippet to have a robust, out-of-the-box search solution.

Site Search - The overlay.
A tidy overlay atop a website. The website in the background is dim and the overlaid box contains blue header links.

If you choose not to use the overlay, the configuration is in your hands. If you would like to have a results container on every page, you can extend your HTML by adding a unique Site Search class: st-search-container to the most suitable content division element.

For example, if you had a basic <div></div> somewhere within your <body></body> tags, you would extend it like so:

<div class="st-search-container"></div>

Your results will now appear within this content division element.

An example which you can interact with is the search experience within Swiftype.com:

Site Search - Swiftype.com search, a relevant result set with multiple facets.
A set of results for the query meta tag - shows multiple facets. It is robust, clean, and full of character.

If you would rather your results appear only within one specific webpage, you would add the st-search-container class to the most appropriate division element, and then specify the page URL within the results container settings within Site Search.

For example, if all search results are display within https://example.com/search_results, you would enter that URL, and ensure that the primary content division element within that page contained the Site Search class.

Basic Appearance

When installing the search field and the results container, you declare the space wherein the JavaScript snippet will send and receive data, respectively. When it comes to what that data will look like, we must customize the appearance. The appearance menu within interface options will help you do just that.

Given that you can adopt your existing search field to use Site Search, its styling is part of your website's design. However, your search and autocomplete results can be customized within Site Search to match your aesthetic and information delivery preferences.

Search Results have a strong relationship with the properties of your documents. By default, the Site Search Crawler will take your webpages and assign them field values: a title, some sections, a url, a published_at date, the body text, and an image to use as a thumbnail, if available.

Site Search - Customizing the appearance of search results.
The appearance menu. The submenu contains the options Appearance, Search Field, Results Container and Overview. The appearance page is shown, which allows you to customize the styling of search results and autocomplete.

Using the result designer, you can choose one of three stylized layout options to display your fields. The content of each option can be adjusted by associating the default fields with the fields of your own choosing.

For example, if you want to use a different URL, select a different secondary attribute other than section, or use alternative description text, you may do so. You can also add custom fields via meta tags, which allow for tremendous flexibility in building your result sets.

The same logic applies to the Autocomplete customization options. Choose your layout style, then associate its fields with the fields of your own choosing. You can choose to disable autocomplete entirely, if you do not need it.

Finally, you can alter the color of the primary links and the highlight text within the Colors menu. You will now receive your Site Search JavaScript snippet to install within your website.

Custom Search Implementations

Custom design work makes use of the Site Search API. Given that the API calls will be search operations, you can apply custom styling to both the Crawler and API Engine types. For custom design work, you are free to use the APIs however you can think to use them. But we have some options you might want to consider before starting from scratch.

We support an open source jQuery Plugin for Site Search that 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.

The common thread between configuration options is the relationship between fields and how those fields are represented within your results. The jQuery plugin shows the next step, which is introducing more sophisticated API calls via scripting.

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 type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script type="text/javascript" src="jquery.ba-hashchange.min.js"></script>
<script type="text/javascript" src="jquery.swiftype.search.js"></script>

This provides you with: (1) jQuery, (2) the jQuery hashchange plugin, and (3) the 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 type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
    <script type="text/javascript" src="jquery.ba-hashchange.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. At its most basic, you can generate a default result set by adding minimal jQuery:

$('#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 type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
    <script type="text/javascript" src="jquery.ba-hashchange.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>');
};

... and (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 allows you to look 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 which shows the styling parameters that you can adjust to build your own style.

Hopefully this is a helpful springboard when designing the most enjoyable search experience which your creative mind can dream. The jQuery Plugin for Site Search README and the jQuery Autocomplete Plugin for Site Search have some deeper instruction as well as access to all of the code.

Site Search supports more than jQuery plugins. You can visit our clients page for links to our Ruby, Node.js, Python, and Java clients.


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