Search JS SDK

Search JS SDK is a javascript helper for communicating with site search API. It is useful for building custom search user interfaces.

To access the SDK search script library must be added:

<script src="{{ site.static_asset_host }}/libs/edicy-search/latest/edicy-search.js"></script>

Initiation and running

// Function to handle the results
var handleSearchResult = function(data) {
  // handle results using data.result object
  // handle pagination and page navigation using data.pages object
  // Look at "Callback data" section below for detailed description
};

// Default parameters for all future searches
var parameters = {
  lang: 'en',
  per_page: 5
};

// Initiate the object
var searchSDK = new VoogSearchSDK(parameters, handleSearchResult);

// Run some search query
searchSDK.query({
  q: "search for this string"
});

Methods

There are two public methods of SDK .query() and .abort()

.abort()

Aborts the current active XMLHttpRequest if any present. If no request is currently running will do nothing.

.query(parameters)

Runs search query with the given parameters. Parameter q (query string), is required. If the request has received some answers, the callback function (handleSearchResult) will be called with results containing data object as parameter.

Query parameters

Parameters for search query are the same as in search API . On SDK initiation, parameter defaults can be given. These defaults will be overwritten by parameters given when invoking .query() method.

q - query string (required).
per_page - elements per response (default: 50; maximum: 250).
page - requested page (default: 1).
lang - optional language filter (e.g. ?q=test&lang=en), returns only pages on given language.
types - optional language filter as string or array (e.g. ?q=test&types=article), returns only pages with given type. Allowed values:
- page - normal pages.
- article - blog articles.
- element - catalog objects.
tags - optional tags filter as string or array (e.g. ?q=test&tags=news) returns only pages/articles with given tag.
path - optional path prefix (e.g. ?q=test&path=/blog or ?q=test&path=/blog/) returns only pages with given prefix.
tag_facets - optional flag to include tags related statistics to response (e.g. ?q=test&tag_facets=true) See an example here.

Callback data

The data object passed to callback function has the following structure:

{
  pages: {
    first: function() {}, // A function calling the first page of pagination
    last: function() {}, //  A function calling the last page of pagination
    prev: function() {}, // A function calling the previous page of pagination. Present if there are previous pages
    next:  function() {}, // A function calling the next page of pagination. Present if there are next pages
    getNr: function(nr) {}, // A function calling page given with nr parameter.
    page: number, // Number of current page
    total: number // Total number of pages present
  },
  result: [ // The results containing array
    {
      description: "Some descripton",
      lang: "en",
      path: "/test/article",
      tags: ["tag1", "tag2"],
      title: "Article — My new site",
      type: "article",
      updated_at: "2015-11-11T12:19:46Z"
    },
    {
      description: "Some other descripton",
      lang: "en",
      path: "/test/article2",
      tags: ["tag1", "tag2"],
      title: "Article2",
      type: "article",
      updated_at: "2015-11-11T12:19:46Z"
    }
  ],
  time_ms: number, // time of query in milliseconds
  totalEntries: 5 // total number of entries found
}

The functions under .pages key are callable in javascript and are for easy navigation in pagination. Search query is invoked and the callback function (handleSearchResult) is called when the request has finished.