feat(urls): ability to create an URL from a set of params

Fix #372

BREAKING CHANGE: the instantsearch.createURL method is now taking a
simple JS object and not a SearchParameter instance anymore.

Author: redox

lib/InstantSearch.js

@@ -59,9 +59,9 @@ Usage: instantsearch({
 
     if (this.urlSync) {
       let syncWidget = urlSyncWidget(this.urlSync);
-      this.createURL = syncWidget.createURL.bind(syncWidget);
+      this._createURL = syncWidget.createURL.bind(syncWidget);
       this.widgets.push(syncWidget);
-    } else this.createURL = defaultCreateURL;
+    } else this._createURL = defaultCreateURL;
 
     this.searchParameters = this.widgets.reduce(enhanceConfiguration, this.searchParameters);
 
@@ -79,6 +79,13 @@ Usage: instantsearch({
     helper.search();
   }
 
+  createURL(params) {
+    if (!this._createURL) {
+      throw new Error('You need to call start() before calling createURL()');
+    }
+    return this._createURL(this.helper.state.setQueryParameters(params));
+  }
+
   _render(helper, results, state) {
     forEach(this.widgets, function(widget) {
       if (!widget.render) {
@@ -89,7 +96,7 @@ Usage: instantsearch({
         results,
         state,
         helper,
-        createURL: this.createURL
+        createURL: this._createURL
       });
     }, this);
     this.emit('render');

lib/__tests__/InstantSearch-test.js

@@ -4,10 +4,14 @@ import EventEmitter from 'events';
 import expect from 'expect';
 import range from 'lodash/utility/range';
 import sinon from 'sinon';
+import jsdom from 'mocha-jsdom';
 
+import SearchParameters from 'algoliasearch-helper/src/SearchParameters';
 import InstantSearch from '../InstantSearch';
 
 describe('InstantSearch lifecycle', () => {
+  jsdom({useEach: true});
+
   var algoliasearch;
   var algoliasearchHelper;
   var client;
@@ -23,7 +27,10 @@ describe('InstantSearch lifecycle', () => {
     helper = new EventEmitter();
 
     helper.search = sinon.spy();
-    helper.state = 'state';
+    helper.getState = sinon.stub().returns({});
+    helper.state = {
+      setQueryParameters: function(params) { return new SearchParameters(params); }
+    };
 
     algoliasearch = sinon.stub().returns(client);
     algoliasearchHelper = sinon.stub().returns(helper);
@@ -41,7 +48,8 @@ describe('InstantSearch lifecycle', () => {
       appId: appId,
       apiKey: apiKey,
       indexName: indexName,
-      searchParameters: searchParameters
+      searchParameters: searchParameters,
+      urlSync: {}
     });
   });
 
@@ -122,7 +130,7 @@ describe('InstantSearch lifecycle', () => {
           expect(widget.render.calledOnce).toBe(true, 'widget.render called once');
           expect(widget.render.args[0])
             .toEqual([{
-              createURL: search.createURL,
+              createURL: search._createURL,
               results,
               state: helper.state,
               helper,
@@ -180,6 +188,10 @@ describe('InstantSearch lifecycle', () => {
       search.start();
     });
 
+    it('creates a URL', () => {
+      expect(search.createURL({hitsPerPage: 42})).toEqual('?q=&hPP=42&idx=&p=0');
+    });
+
     it('emits render when all render are done (using on)', () => {
       var onRender = sinon.spy();
       search.on('render', onRender);

lib/__tests__/main-test.js

@@ -18,6 +18,15 @@ describe('instantsearch()', () => {
     expect(instantsearch.version).toEqual(pkg.version);
   });
 
+  it('statically creates a URL', () => {
+    expect(instantsearch.createQueryString({hitsPerPage: 42})).toEqual('hPP=42');
+  });
+
+  it('statically creates a complex URL', () => {
+    expect(instantsearch.createQueryString({hitsPerPage: 42, facetsRefinements: {category: 'Home'}}))
+      .toEqual('hPP=42&fR[category]=Home');
+  });
+
   it('includes the widget functions', () => {
     var forEach = require('lodash/collection/forEach');
     forEach(instantsearch.widgets, function(widget) {

lib/main.js

@@ -5,6 +5,7 @@ var toFactory = require('to-factory');
 
 var InstantSearch = require('./InstantSearch');
 var instantsearch = toFactory(InstantSearch);
+var algoliasearchHelper = require('algoliasearch-helper');
 
 instantsearch.widgets = {
   hierarchicalMenu: require('../widgets/hierarchical-menu/hierarchical-menu.js'),
@@ -23,4 +24,6 @@ instantsearch.widgets = {
 
 instantsearch.version = require('./version.js');
 
+instantsearch.createQueryString = algoliasearchHelper.url.getQueryStringFromState;
+
 module.exports = instantsearch;