feat(url-sync): use the new mapping option

Closes #838

Author: Jerska

dev/app.js

@@ -5,7 +5,14 @@ var search = instantsearch({
   appId: 'latency',
   apiKey: '6be0576ff61c053d5f9a3225e2a90f76',
   indexName: 'instant_search',
-  urlSync: window.history && 'pushState' in window.history ? true : {useHash: true}
+  urlSync: {
+    useHash: !(window.history && 'pushState' in window.history),
+    mapping: {
+      q: 'query',
+      hPP: 'hits',
+      hFR: 'hierarchical'
+    }
+  }
 });
 
 search.addWidget(

src/lib/InstantSearch.js

@@ -18,23 +18,26 @@ function defaultCreateURL() { return '#'; }
  * @param  {string} options.indexName The name of the main index
  * @param  {string} [options.numberLocale] The locale used to display numbers. This will be passed
  * to Number.prototype.toLocaleString()
+ * @param  {function} [options.searchFunction] A hook that will be called each time a search needs to be done, with the
+ * helper as a parameter. It's your responsibility to call helper.search(). This option allows you to avoid doing
+ * searches at page load for example.
  * @param  {Object} [options.searchParameters] Additional parameters to pass to
  * the Algolia API.
  * [Full documentation](https://community.algolia.com/algoliasearch-helper-js/docs/SearchParameters.html)
  * @param  {Object|boolean} [options.urlSync] Url synchronization configuration.
  * Setting to `true` will synchronize the needed search parameters with the browser url.
+ * @param  {Object} [options.urlSync.mapping] Object used to define replacement query
+ * parameter to use in place of another. Keys are current query parameters
+ * and value the new value, e.g. `{ q: 'query' }`.
+ * @param  {number} [options.urlSync.threshold] Time in ms after which a new
+ * state is created in the browser history. The default value is 700.
  * @param  {string[]} [options.urlSync.trackedParameters] Parameters that will
  * be synchronized in the URL. By default, it will track the query, all the
  * refinable attribute (facets and numeric filters), the index and the page.
  * [Full documentation](https://community.algolia.com/algoliasearch-helper-js/docs/SearchParameters.html)
  * @param  {boolean} [options.urlSync.useHash] If set to true, the url will be
  * hash based. Otherwise, it'll use the query parameters using the modern
  * history API.
- * @param  {number} [options.urlSync.threshold] Time in ms after which a new
- * state is created in the browser history. The default value is 700.
- * @param  {function} [options.searchFunction] A hook that will be called each time a search needs to be done, with the
- * helper as a parameter. It's your responsibility to call helper.search(). This option allows you to avoid doing
- * searches at page load for example.
  * @return {Object} the instantsearch instance
  */
 class InstantSearch extends EventEmitter {

src/lib/url-sync.js

@@ -107,14 +107,15 @@ class URLSync {
     this.urlUtils = urlUtils;
     this.originalConfig = null;
     this.timer = timerMaker(Date.now());
+    this.mapping = options.mapping || {};
     this.threshold = options.threshold || 700;
     this.trackedParameters = options.trackedParameters || ['query', 'attribute:*', 'index', 'page', 'hitsPerPage'];
   }
 
   getConfiguration(currentConfiguration) {
     this.originalConfig = currentConfiguration;
     let queryString = this.urlUtils.readUrl();
-    let config = AlgoliaSearchHelper.getConfigurationFromQueryString(queryString);
+    let config = AlgoliaSearchHelper.getConfigurationFromQueryString(queryString, {mapping: this.mapping});
     return config;
   }
 
@@ -137,12 +138,15 @@ class URLSync {
 
   renderURLFromState(state) {
     let currentQueryString = this.urlUtils.readUrl();
-    let foreignConfig = AlgoliaSearchHelper.getForeignConfigurationInQueryString(currentQueryString);
+    let foreignConfig = AlgoliaSearchHelper.getForeignConfigurationInQueryString(currentQueryString, {mapping: this.mapping});
     foreignConfig.is_v = majorVersionNumber;
 
     let qs = urlHelper.getQueryStringFromState(
       state.filter(this.trackedParameters),
-      {moreAttributes: foreignConfig}
+      {
+        moreAttributes: foreignConfig,
+        mapping: this.mapping
+      }
     );
 
     if (this.timer() < this.threshold) {
@@ -157,17 +161,17 @@ class URLSync {
   createURL(state) {
     let currentQueryString = this.urlUtils.readUrl();
     let filteredState = state.filter(this.trackedParameters);
-    let foreignConfig = algoliasearchHelper.url.getUnrecognizedParametersInQueryString(currentQueryString);
+    let foreignConfig = algoliasearchHelper.url.getUnrecognizedParametersInQueryString(currentQueryString, {mapping: this.mapping});
     // Add instantsearch version to reconciliate old url with newer versions
     foreignConfig.is_v = majorVersionNumber;
 
-    return this.urlUtils.createURL(algoliasearchHelper.url.getQueryStringFromState(filteredState));
+    return this.urlUtils.createURL(algoliasearchHelper.url.getQueryStringFromState(filteredState, {mapping: this.mapping}));
   }
 
   onHistoryChange(fn) {
     this.urlUtils.onpopstate(() => {
       let qs = this.urlUtils.readUrl();
-      let partialState = AlgoliaSearchHelper.getConfigurationFromQueryString(qs);
+      let partialState = AlgoliaSearchHelper.getConfigurationFromQueryString(qs, {mapping: this.mapping});
       let fullState = merge({}, this.originalConfig, partialState);
       fn(fullState);
     });