NAV

Introduction

/*
 * Initialize the custom client with all of the preconfigured options
 */
var search = new ConstructorioSearch.default({});

/*
 * Perform a search on initial page load
 */
window.addEventListener('load', function() {
  search.requestResults();
});

The Constructor.io JavaScript search client provides a front-end search interface to display search results.

The search client renders specific UI components into designated HTML elements on your search page. The search client also provides event handlers for you to respond to user actions.

Every Constructor.io customer gets their own customized version of the search client, one that comes with UI options preconfigured to match their existing search page. The simplest integration on a search page therefore looks like the code on the right.

Adding the search client script to your search page will automatically inject a minimal set of styles onto your page. These styles will only reference those areas of the search page that the search client renders.

Returning Results

/*
 * Simple integration.  The custom client internally translates the current
 * URL into a search request and makes an AJAX request to return results.
 */
window.addEventListener('load', function() {
  search.requestResults();
});
/*
 * Complex integration.  Every custom client has a getRequestFromUrl() 
 * function that is specific to the customer website and translates their URL 
 * structure into a search request object.
 */
window.addEventListener('load', function() {
  var request = search.getRequestFromUrl(window.location.href);
  if (request.term) {
    search.requestResults(request);
  }
});

To show results on your search page, first you need to translate the page URL into a search request object. Then, if the search request contains a search term, tell the client to request results. When the results are received by the client, it will automatically populate the components configured in the UI options.

Responding to Events

/*
 * The client has received and is displaying results.
 */
search.on('received.results', function(results) {
  var request = search.getRequestFromUrl(window.location.href);
  ga('send', 'event', 'search results', 'loaded', request.term, results.total_num_results);
});

/* 
 * The user has clicked on a search result.  If this event has no handlers, 
 * the client will automatically send users to the URL of the associated result.
 */
search.on('clicked.result', function(info, result) {
  window.location = result.data.url;
});

/* 
 * The user has clicked on a section result.   If this event has no handlers, 
 * the client will automatically send users to the URL of the associated result.
 */
search.on('clicked.sectionResult', function(info, result, sectionName) {
  window.location = result.data.url;
});

/* 
 * The user has requested a new page of search results by clicking on a UI 
 * component such as a facet, a group, or a pager. Every custom search client 
 * has a getUrlFromRequest() function that is specific to the customer 
 * website and translates a search request object into a search URL.   If this 
 * event has no handlers, the client will automatically send users to a new page.
 */
search.on('update.request', function(request) {
  var url = search.getUrlFromRequest(request);
  window.location = url;
});

When a user interacts with the search client or when Constructor.io services communicate with the search client, the client emits its own events that the page can handle. Here are a list of the events available and the data that they send.

Note that all events are optional, but that for some events if there are no handlers the search client will handle the event in a sensible manner.

UI Options

var options = {
  uiOptions: {

    /*
     * Facets are filters that usually relate to a product's brand, size, color, 
     * etc.  Selecting or deselecting a facet will cause an 'update.request' event.
     */
    facets: {
      selector: '#facets',
      renderFacet: (props) => {},
      renderFacetHeader: (props) => {},
    },

    /* 
     * Groups are filters that pertain to a category that a product belongs to 
     * (i.e. Apple in Fruits).  Selecting or deselecting a group will cause an 
     * 'update.request' event.
     */
    groups: {
      selector: '#groups',
      renderGroup: (props) => {},
      renderGroupHeader: (props) => {},
    },

    /* 
     * Header displays the term and number of results returned for the 
     * current search query
     */
    header: {
      selector: '#results-header',
      renderHeader: (props) => {},
    },

    /* 
     * Setting infinite scroll to true will display more results when the user 
     * scrolls to the bottom of the page. If this happens it will cause a 
     * 'received.results' event.
     */
    infiniteScroll: false,

    /* 
     * Pager allows the user to choose how many results are displayed.
     * Selecting a new number of results per page will cause an 'update.request' event.
     */
    pager: {
      selector: '#pager',
      resultsPerPageOptions: [20, 40, 60],
      renderPager: (props) => {},
    },

    /*
     * Pagination displays page navigation. Selecting a new page will cause 
     * an 'update.request' event.
     */
    pagination: {
      selector: '#paginator',
      renderPreviousPage: (props) => {},
      renderFirstPage: (props) => {},
      renderPage: (props) => {},
      renderPageSpacer: (props) => {},
      renderLastPage: (props) => {},
      renderNextPage: (props) => {},
    },

    /*
     * Results displays the actual search results.  Each search result is 
     * rendered individually by the rendering function.   Clicking anywhere on a 
     * result will cause a 'clicked.result' event.
     */
    results: {
      selector: '#results-list',
      renderResult: (props) => {},
    },

    /*
     * Sections gives customers the opportunity to display data from additional 
     * sections ingested by Constructor.io, such as displaying product 
     * categories related to a term in addition to products.  Clicking 
     * anywhere on a section result will cause a 'clicked.sectionResult' event.
     */
    sections: {
      categories: {
        maxResults: 8,
        sectionName: 'Categories',
        selector: '#category-results',
        renderSectionHeader: (props) => {},
        renderSectionResult: (props) => {},
      }
    },

    /*
     * Zero Results displays when there are no results for a search query after
     * the client receives a response from the server
     */
    zeroResults: {
      selector: '#zero-results',
      renderZeroResults: (props) => {},
    },

    /*
     * Loading displays when the client is fetching results from the server
     */
    loading: {
      selector: '#search-loader',
      renderLoading: (props) => {},
    },

    /*
     * Error displays when the client has not been able to fetch results 
     * from the server for any reason.
     */
    error: {
      selector: '#error',
      renderError: (props) => {},
    },
  }
} 

/*
 * Create the client with new options
 */
var search = new ConstructorioSearch.default(options);

There are many options for the search client. Most of the options involve instructing the search client to render a specific component inside of a designated HTML element on the search page. Every option is optional. If an option is missing then the search client does not render that component. On the right is a comprehensive list of the current options we support.

Note that all rendering functions must return either a React Component or an HTML string. If a renderer returns an HTML string it will be run through a sanitizer before rendering for security reasons.

Additionally, all rendering functions take a single argument, props, of type object. The individual keys on that object vary by rendering function.

If any option is incorrectly configured for the client, a warning will show up in the JavaScript console and that option will be ignored.

Debugging

/*
 * Get configuration information
 */
search.help()

The search client uses the React Framework. One easy way to debug it is to use the React Developer Tools. You may also use the help() function, which will output useful information about the client’s configuration to the browser console.