Migration guide : V1 to V2

Configuring the helper

The configuration is similar to V1 :

var client = algoliasearch( "applicationId", "apiKey" );

var helper = algoliasearchHelper( client, "myMainIndex", { 
  facets : [ "mainCharacterFirstName", "year" ],
  disjunctiveFacets : [ "director" ]
} );

The configuration is pretty much the same but all the parameters are specified by the SearchParameters.

Getting the response

The V1 was based on callback. With the search() method you would trigger the search and once the results were fetched it would call the provided callback: providing an error if applicable and the results otherwise.

In V1, it looked like that:

helper.search( "query", function( err, result ){
  if( err ) {
    //error handling
    return;
  }
  else {
    //Let's use the result
  }
});

The newest version relies on events to give the results back. Two events can be triggered depending on whether you received an error: result and error.

In V2, it looks like that :

helper.on( "result", function( result ) {
  //using the result
} );

helper.on( "error", function( err ) {
  //error handling
} );

// Change the query and then trigger the search
helper.setQuery( "query" ).search();

Configuring a query

The V2 propose a chainable API to set the state of the search. Also no setters will ever trigger a search by itself.

// salePrice is defined as a disjunctive facet
helper.setQuery( $q.val() )
      .addNumericRefinement( "salePrice", ">", 100 )
      .addNumericRefinement( "salePrice", "<", 400 )
      .addRefine( "category", "watch" )
      .search();

You don't have to store those parameters on your side, they are available in the state property of the helper.

var currentMin = helper.state.numericRefinements[ "salePrice" ][ ">" ];
var currentMax = helper.state.numericRefinements[ "salePrice" ][ "<" ];

var currentQuery = helper.state.query;

var currentlyRefinedCategory = helper.state.facetsRefinements[ "category" ];

Handling the facets

The format of the response you get from the helper is different from the one you get from the raw API. The helper's job is to make your life easier and so it aggregates the several responses it gets from Algolia API into one consistent object. This is especially true for facets handling.

To help you further in processing those data, we've made some changes in the way the facets are structured.

Facets are in the order of the configuration

Facets and disjunctive facets attributes in the response are now arrays instead of objects. Therefore going through the facets as you ordered them is now trivial.

Yet it makes it harder to get to a specifically named facet. That's why we also added a method to the response : getFacetByName.

This last method works with facets and disjunctive facets.

V1:

helper.search( "", function( err, results ){
  if( err ) return; // ERROR
  else {
    for( var facetName in results.disjunctiveFacets ) {
      renderFacet( results.disjunctiveFacets[ facetName ] );
    }
    renderFacet( results.disjunctiveFacets[ "salePrice" ] );
  }
} );

V2:

helper.on( "change", function( results ) {
  // Render all the facets
  results.disjunctiveFacets.forEach( function( f ) {
    renderFacet( f );
  } );
  // Get a specific facet by name
  renderFacet( results.getFacetByName( "salePrice" ) );
} );

Facets information are aggregated in the same place

We also made a few changes in the way the facet informations are aggregated. There are no more facetsStats objects, those stats are now aggregated in the facets and disjunctiveFacets attributes.

In V1, it looked like that:

{
   "facets_stats" : {
      "salePrice" : {
         "min" : 0.49,
         "max" : 5999.98,
         "avg" : 124.627
      }
   },
   "disjunctiveFacets" : {
      "category" : {
         "Movies & TV Shows" : 1574,
         "Headphones" : 188,
         "iPad Cases, Covers & Sleeves" : 165,
         "Flat-Panel TVs" : 190,
         "Cell Phone Cases & Clips" : 572
      }
   },
   "facets" : {
      "salePrice" : {
         "39.99" : 436,
         "9.99" : 528,
         "19.99" : 669,
         "29.99" : 456,
         "14.99" : 428
      },
      "shipping" : {
         "Free shipping" : 5507
      }
   },
   "hits" : [
     ...
   ],
   ...
}

V2 response:

{
   "facets" : [
      {
         "data" : {
            "14.99" : 428,
            "9.99" : 528,
            "29.99" : 456,
            "19.99" : 669,
            "39.99" : 436
         },
         "stats" : {
            "avg" : 124.627,
            "min" : 0.49,
            "max" : 5999.98
         },
         "name" : "salePrice"
      }
   ],
   "disjunctiveFacets" : [
      {
         "data" : {
            "Flat-Panel TVs" : 190,
            "Cell Phone Cases & Clips" : 572,
            "Headphones" : 188,
            "iPad Cases, Covers & Sleeves" : 165,
            "Movies & TV Shows" : 1574
         },
         "name" : "category"
      },
   ],
   "hits" : [
     ...
   ],
   ...
}

Thinking with the helper

The API of V2 is almost the same as the one from V1. There is notable change, though. There is only one method that will trigger a search to Algolia: helper.search. The others will either let you change the current state or read information of the state directly.

The state is an object attached on the state property of the helper.

// We start we a new helper. The query is set to "" by default

// Now we set a value to it
helper.setQuery( "my query" );

// The search state has changed and the value for query is "my query"
helper.state.query === "my query"; // true

// NB : no search has been triggered yet
// Let's trigger it!
helper.search();

// Now the "result" event has been triggered and the result will eventually be
// handled by the event handler.

The complete documentation of methods of the helper is available in the jsdoc