Interacting with your Kapsule

Your Kapsule comes with a Javascript API to interact with its powerful search features.

There are two parts in the Javascript API:

  • The Functions to call on User's actions.
  • The Callbacks to declare and code to handle Kapsule's answers.

Functions

Init

Kapsule works on a system of callbacks to render the results of a search (as well as facets and filters) to the DOM. On page load the kapsule should be initialized with callbacks provided by the user.

Load kapsule with the This should be declared once on page load.

  1. Decompress all resources (index and docstore)
  2. Load index
  3. Add displayResults callback to render results to page
  4. Add displayFacets callback to render facets to page

init (kwargs)

Arguments
Returns
  • loaded (Boolean) - Return the status of the kapsule

Example

var displayResults = function(searchResults){
    // you would normally update the DOM here
    console.log(searchResults)
};

var displayFacets = function(facets){
    // you would normally update the DOM here
    console.log(facets)
};

kapsule.init({
    displayResults: displayResults,
    displayFacets: displayFacets
});

Search

On calling the search method, a query is made against the index contained in the kapsule. Search results are not returned directly from the method, rather the method triggers callbacks for displayResults and displayFacets.

  • Reset the params from previous search
  • Manage the timer
  • Query the search index
  • Filter the index if facets/ filters are active
  • Update the state with results from the search
  • Call the displayResults method to render the results to the page
  • Compute facets if necessary
  • Call displayFacets
  • Return a status with status 'OK', or 'ERROR' and a message.

search (params)

Arguments
  • params.terms (Object) – Object containing {terms: “foobar”}
Returns
  • SuccessStatus.status (String) – The status of the getPage (error or success)
  • SuccessStatus.message (String) – The error message if status is ERROR

Example

kapsule.search({'terms': 'Chuck Norris'});

Triggers

Once the results are retreived, they need to be displayed to the user. This is done using the callbacks passed in the init method. Search will trigger the following callbacks:

Reset

The reset function is responsible for resetting information from the previous search. This includes:

  • Search results
  • The current page number (for pagination)
  • Active facets and filters
  • Search terms

reset ()

There is no parameters for this function.

Example

kapsule.reset();

Settings

Settings returns current settings for the kapsule. This currently includes:

  • id - The id of the kapsule
  • name - The name of the kapsule
  • template - 'instant' or 'classic' depending on the type of kapsule created
  • min_chars - The minimum charagters for instant search

Example

kapsule.settings;

GetPage

Kapsule returns a snapshot of the results returned from the search to aid with pagination. The default results per page is set to 10, so an initial search would return results 1 to 10.

Get page will return either the page requested (as long as it exists), if it is passed a numeric value, or the page relative to the current page if passed one of the following string values:

  • next
  • previous
  • first
  • last

If the page does not exist (you cannot have a previous page to page 1), an error will be returned.

getPage (page, append[optional])

Arguments
  • page (Int | String) Either the page number as an integer, or 'first', 'last', 'next', 'previous', which will yield the page relative to the current page
  • append (Boolean) This parameter is used for infinite scrolling. If append is true, the value of the page will be verified to make sure that it corresponds with the next page. append will then be passed to the displayResults function
Returns
  • SuccessStatus.status (String) – The status of the getPage (error or success)
  • SuccessStatus.message (String) – The error message if status is ERROR

Example

kapsule.getPage('next');       // retreive next page
kapsule.getPage('next', true); // retreive current and next page
kapsule.getPage(10);           // retreive page 10

SelectFacet

Facets are used to filter the results in the search, before the results are displayed. More information on facets can be found TODO: here.

Adding a facet requires the user to provide the facet category name. Multiple facet categories may be present per search, and multiple facet values may be active per facet category.

Note. when the callback displayFacets is called, all facets (active an inactive) are accessible. Each facet has a prebuilt callback to either select or unselect a facet. It is recommended to use this as a way of activating or deactivating a facet. More on this subject can be found TODO: here.

selectFacet (jsonPath, value)

Arguments
  • jsonPath (String) - The name of the category of the facet
  • value (String) - The value by which you wish to facet
Returns
  • None

Example

kapsule.selectFacet('actor', 'Chuck Norris');

Triggers

Adding a facet will relaunch the following callbacks:

This should be intuitive, as refining the results (applying a filter to the results from the initial search), will require that the search results be updated. The facets will also change with application of a facet, thus we will need to re render the facets.

UnselectFacet

To remove a facet, the user can provide details of the facet category name and value to the unselectFacet Endpoint.

It is again important to note that you can utilise the callback provided in the displayFacets callback to add a deselect facet event to the DOM.

Note. all facets will be reset using the kapsule.reset() method

unselectFacet (jsonPath, value)

Arguments
  • jsonPath (String) - The name of the category of the facet
  • value (String) - The value by which you no longer wish to facet
Returns
  • None

Example

kapsule.unselectFacet('actor', ' Keanu Reeves');

Triggers

As with adding a facet, removing a facet will launch the following callbacks:

Callbacks

displayResults

This callback is used to add search results to the DOM. This will be called by search, selectFacet and unselectFacet methods. The callback takes one argument, lets call this searchResults. Here is an example of a searchResults object:

displayResults (searchResults)

{
    page: 1,
    time: "0.000670",
    totalPages: 1,
    totalResults: 10,
    data: [
        {country: "CA", lat: 48.61667, lng: -93.4003, name: "Fort Frances"},
        {country: "MU", lat: -20.37056, lng: 57.56111, name: "Nouvelle France"},
        {country: "FR", lat: 48.94956, lng: 2.5684, name: "Tremblay-en-France"},
        {country: "FR", lat: 49.00443, lng: 2.51703, name: "Roissy-en-France"},
        {country: "FR", lat: 49.05552, lng: 2.50035, name: "Puiseux-en-France"},
        {country: "FR", lat: 49.08837, lng: 2.37159, name: "Belloy-en-France"},
        {country: "FR", lat: 49.06187, lng: 2.2988, name: "Baillet-en-France"},
        {country: "FR", lat: 47.77586, lng: 4.16361, name: "Ancy-le-Franc"},
        {country: "MQ", lat: 14.60365, lng: -61.07418, name: "Fort-de-France"},
        {country: "FR", lat: 48.43387, lng: -4.56809, name: "Rd pt des Chataigniers, Rte de Miliza..."}
    ]
}
Arguments
  • page (Numeric) - The page number
  • time (String) - The time as a string in seconds
  • totalPages (Numeric) - Total pages returned from search
  • totalResults (Numeric) - Total results returned from search
  • data (Array.Objects) - The results returned from the search
    • An object containing category names as keys and category values as values.
Returns
  • None

Example usage:

var displayResults = function(searchResults){
  // looking at the results...
  console.log(searchResults.page) // 1
  console.log(searchResults.time) // "0.000670"
  console.log(searchResults.totalPages) // 1
  console.log(searchResults.totalResults) // 10
  for(searchResult of searchResults){
      console.log(searchResult) // {country: "CA", lat: 48.61667, lng: -93.4003, name: "Fort Frances"} ...
  }
}

DisplayFacets

The callback displayFacets is called on launching a search or updating the facets. The callback takes one argument, which will be an object in the format below:

displayFacets (facets)

[
    {
        jsonPath: 'country',
        values: [
            {value: "FR", count: 7, selected: false, update: ƒ},
            {value: "CA", count: 1, selected: false, update: ƒ},
            {value: "MU", count: 1, selected: false, update: ƒ},
            {value: "MQ", count: 1, selected: false, update: ƒ},
        ]
    },
    ...
]

The json path represents the name of the category for which the categories can be selected. In the values array, we see a list of selectable values, with their status (are they selected or not) and a callback for toggling selection (see updates argument below)

Arguments
  • jsonPath (String) the category title
  • values (Array.Objects) The available choices for based on the current search
    • value (String) the value of the facet
    • count (Numeric) the number of results with this value
    • selected (Boolean) is the facet active
    • update (function) a convenient callback to add to an li element. This callback will call the selectFacet method if the selected value is false and unselectFacet in the case it's true. As an example, if we called the facets.values[1].update callback, we would be running kapsule.selectFacet('country', 'CA').
Returns
  • None

DisplayFilters

The callback displayFilters is called on launching a search or updating the facets. The callback takes one argument, which will be an object in the format below:

displayFilters (filters)

[
    {
    jsonPath: 'country',
    operations: {
        equal: [{value: "ES", update: ƒ}, ...]
        }
    },
    ...
]

The json path represents the name of the category for which a filter is active. Operations holds each possible filtering opeartion, like "equal", "greater", and so on. For each of these operations, you can find the active filters and what they filter on, in this case "ES". Similarly to what is done for facets, you will also find a callback to handle toggling of this filter.

Arguments
  • jsonPath (String) the category title
  • operations (Object) The active filtering operations for this category.
    • equal (Object.Array) The equal filter and associated values.
    • value (String) One of the operand of the filter.
    • update (function) A convenient callback to add on click event. This callback will call the unselectFacet method. As an example, if we called the filters.operations.equal[1].update callback, we would be running kapsule.unselectFacet('country', 'ES').
Returns
  • None