feat(configure): expose configure method (#637)

* feat(geolocation-permission): expose unstable_configure method * fix(geolocation-permission): add tests for configure method for both controls and parameters * feat(geolocation-permission): remove unstable_ prefix * chore(configure): improve docs and make configure safer * chore(configure): add small docstring about why certain fields are ignored * test(configure): add tests to validate reset behaviour * feat(configure): make .configure return the places instance * doc(configure): split options documentation in three parts to better explain static vs reconfigurable options * doc(configure): update examples to use configure * refact(configure): move configure to separate file * chore(configure): update single country search with dynamic example * test(configure): check that places.configure ignores unsafe options * doc(configure): add dynamic example with countries, type, language and hitsPerPage * doc(configure): make example more IE11 compliant
algolia · Nov 21, 2018 · 853f0d7 · 853f0d7
1 parent f8eac3b
commit 853f0d7
Show file tree

Hide file tree

Showing 14 changed files with 789 additions and 159 deletions.
diff --git a/docs/source/documentation.html.md.erb b/docs/source/documentation.html.md.erb
@@ -78,7 +78,7 @@ As a result, you will get the Algolia Places autocompletion menu:
 To turn any HTML `<input />` into an address search bar make sure you include the `places.js` library and use the following initialization code:
 
 ```js
-var options = {
+const options = {
  appId: 'YOUR_PLACES_APP_ID',
  apiKey: 'YOUR_PLACES_API_KEY',
  container: '#my-input-DOM-selector',
@@ -90,16 +90,24 @@ places(options);
 Advanced example using all parameters:
 
 ```js
-var options = {
+const fixedOptions = {
  appId: 'YOUR_PLACES_APP_ID',
  apiKey: 'YOUR_PLACES_API_KEY',
  container: document.querySelector('#demo'),
+};
+
+const reconfigurableOptions = {
  language: 'de', // Receives results in German
  countries: ['us', 'ru'], // Search in the United States of America and in the Russian Federation
  type: 'city', // Search only for cities names
  aroundLatLngViaIP: false // disable the extra search/boost around the source IP
 };
-places(options);
+const placesInstance = places(fixedOptions).configure(reconfigurableOptions);
+
+// dynamically reconfigure options
+placesInstance.configure({
+ countries: ['us'] // only search in the United States, the rest of the settings are unchanged: we're still searching for cities in German.
+})
 ```
 
 Tip: _Places application IDs **always** start by_ `pl`, _which makes them recognizable at a glance._
@@ -109,10 +117,16 @@ _If you do not have a Places application, you can create one by [signing up for
 
 Here are the options you can pass to the `places(options)` function:
 
+##### Static options
+These options can only be set during the instantiation of the places application using
+```js
+const placesInstance = places(options)
+```
+
 <!-- Indentation is on purpose for <td>s, to allow HTML inside markdown -->
 <table class="api">
  <thead><tr>
- <th>Option</th>
+ <th>Static Option</th>
  <th>Description</th>
  </tr></thead>
  <tbody>
@@ -129,10 +143,95 @@ Determines the `<input>` that will be used for the Algolia Places autocompletion
 
 You just need to pass a reference to an Element. Obtained via
 [document.querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector) for example.
+
+**Important**: This parameter can only be set at instantiation.
+</td>
+ </tr>
+ <tr>
+<td markdown="1">
+<div class="api-entry" id="api-options-appId"><code>appId</code></div>
+
+Type: **string**
+</td>
+<td markdown="1">
+The Places application ID to use.
+
+**Note**: Create a <a href="https://www.algolia.com/users/sign_up/places">Places app here</a>.
+
+**Important**: This parameter can only be set at instantiation.
+</td>
+ </tr>
+ <tr>
+<td markdown="1">
+<div class="api-entry" id="api-options-apiKey"><code>apiKey</code></div>
+
+Type: **string**
+</td>
+<td markdown="1">
+The Places search API key to use.
+
+**Important**: This parameter can only be set at instantiation.
 </td>
  </tr>
  <tr>
 <td markdown="1">
+<div class="api-entry" id="api-options-templates"><code>templates</code></div>
+
+Type: **Object**
+</td>
+<td markdown="1">
+Change the templates used in place.js.
+
+Available templates:
+
+- value
+- suggestion
+
+Each template is a function that will receive a [suggestion object](#suggestions) and must return
+a `string`.
+
+`value` must return a plain string as it's used to fill the `input.value`. `suggestion` should
+return an HTML string to be displayed in the dropdown.
+</td>
+ </tr>
+ <tr>
+<td markdown="1">
+<div class="api-entry" id="api-options-style"><code>style</code></div>
+
+Type: **boolean**
+</td>
+<td markdown="1">
+Control whether the default styles should be used.
+
+**Default**: Styles are enabled.
+
+**Important**: This parameter can only be set at instantiation.
+</td>
+ </tr>
+ </tbody>
+</table>
+
+##### Reconfigurable options
+These options can be set during the instantiation of the places application using
+
+```js
+const placesInstance = places(options)
+```
+
+or at any time using
+
+```js
+placesInstance.configure(options)
+```
+
+<table class="api">
+ <thead><tr>
+ <th>Reconfigurable option</th>
+ <th>Description</th>
+ </tr></thead>
+ <tbody>
+ <tr>
+<td markdown="1">
 <div class="api-entry" id="api-options-type"><code>type</code></div>
 
 Type: **string**
@@ -219,60 +318,43 @@ given the area density.
  </tr>
  <tr>
 <td markdown="1">
-<div class="api-entry" id="api-options-templates"><code>templates</code></div>
-
-Type: **Object**
-</td>
-<td markdown="1">
-Change the templates used in place.js.
-
-Available templates:
-
-- value
-- suggestion
-
-Each template is a function that will receive a [suggestion object](#suggestions) and must return
-a `string`.
+<div class="api-entry" id="api-options-insideBoundingBox"><code>insideBoundingBox</code></div>
 
-`value` must return a plain string as it's used to fill the `input.value`. `suggestion` should
-return an HTML string to be displayed in the dropdown.
+Type: **string**
 </td>
- </tr>
- <tr>
 <td markdown="1">
-<div class="api-entry" id="api-options-style"><code>style</code></div>
+Filters the results inside the area defined by the two extreme points of a rectangle. [See guide](https://www.algolia.com/doc/guides/geo-search/geo-search-overview/#insideboundingbox).
 
-Type: **boolean**
-</td>
-<td markdown="1">
-Control whether the default styles should be used.
+Format: `topRightLat, topRightLng, bottomLeftLat, bottomLeftLng`
 
-**Default**: Styles are enabled.
+Example: `"60, 16, 40, -4"`
 </td>
-  </tr>
-  <tr>
+ </tr>
+ <tr>
 <td markdown="1">
-<div class="api-entry" id="api-options-appId"><code>appId</code></div>
+<div class="api-entry" id="api-options-insidePolygon"><code>insidePolygon</code></div>
 
 Type: **string**
 </td>
 <td markdown="1">
-The Places application ID to use.
+Filters the results inside the area defined by a shape. [See guide](https://www.algolia.com/doc/guides/geo-search/geo-search-overview/#insidepolygon).
 
-**Note**: Create a <a href="https://www.algolia.com/users/sign_up/places">Places app here</a>.
+Format: `p1Lat, p1Lng, p2Lat, p2Lng, p3Lat, p3Lng...`
 </td>
- </tr>
- <tr>
+</tr>
+<tr>
 <td markdown="1">
-<div class="api-entry" id="api-options-apiKey"><code>apiKey</code></div>
+<div class="api-entry" id="api-options-getRankingInfo"><code>getRankingInfo</code></div>
 
-Type: **string**
+Type: **boolean**
 </td>
 <td markdown="1">
-The Places search API key to use.
+Controls whether the [_rankingInfo](https://www.algolia.com/doc/api-reference/api-methods/search/#method-response-_rankinginfo) object should be included in the hits. This defaults to `false`.
+
+The _rankingInfo object for a Places query is slightly different from a regular Algolia query and you can read up more about the difference and how to leverage them in [our guide](examples.html#using-_rankinginfo).
 </td>
-  </tr>
-  <tr>
+ </tr>
+ <tr>
 <td markdown="1">
 <div class="api-entry" id="api-options-useDeviceLocation"><code>useDeviceLocation</code></div>
 
@@ -292,6 +374,24 @@ Type: **object**
 Allows you to override computed query parameters sent to the [Algolia Places REST API](rest.html).
 </td>
  </tr>
+</tbody>
+</table>
+
+##### Advanced static options
+These are very advanced options that can be only set during the instantiation of the places application using 
+
+```js
+const placesInstance = places(options)
+```
+
+These options should not be considered for regular use cases.
+
+<table class="api">
+ <thead><tr>
+ <th>Advanced static option</th>
+ <th>Description</th>
+ </tr></thead>
+ <tbody>
  <tr>
 <td markdown="1">
 <div class="api-entry" id="api-options-clientOptions"><code>clientOptions</code></div>
@@ -301,7 +401,7 @@ Type: **object**
 <td markdown="1">
 Algolia [JavaScript API client options](https:/algolia/algoliasearch-client-js#client-options).
 
-This is an advanced option.
+**Note:** This is an advanced option.
 </td>
  </tr>
  <tr>
@@ -313,46 +413,10 @@ Type: **object**
 <td markdown="1">
 [autocomplete.js options](https:/algolia/autocomplete.js#options) to configure the underlying
 autocomplete.js instance.
-</td>
- </tr>
- <tr>
-<td markdown="1">
-<div class="api-entry" id="api-options-insideBoundingBox"><code>insideBoundingBox</code></div>
-
-Type: **string**
-</td>
-<td markdown="1">
-Filters the results inside the area defined by the two extreme points of a rectangle. [See guide](https://www.algolia.com/doc/guides/geo-search/geo-search-overview/#insideboundingbox).
 
-Format: `topRightLat, topRightLng, bottomLeftLat, bottomLeftLng`
-
-Example: `"60, 16, 40, -4"`
+**Note:** This is an advanced option.
 </td>
- </tr>
- <tr>
-<td markdown="1">
-<div class="api-entry" id="api-options-insidePolygon"><code>insidePolygon</code></div>
-
-Type: **string**
-</td>
-<td markdown="1">
-Filters the results inside the area defined by a shape. [See guide](https://www.algolia.com/doc/guides/geo-search/geo-search-overview/#insidepolygon).
-
-Format: `p1Lat, p1Lng, p2Lat, p2Lng, p3Lat, p3Lng...`
-</td>
-</tr>
-<tr>
-<td markdown="1">
-<div class="api-entry" id="api-options-getRankingInfo"><code>getRankingInfo</code></div>
-
-Type: **boolean**
-</td>
-<td markdown="1">
-Controls whether the [_rankingInfo](https://www.algolia.com/doc/api-reference/api-methods/search/#method-response-_rankinginfo) object should be included in the hits. This defaults to `false`.
-
-The _rankingInfo object for a Places query is slightly different from a regular Algolia query and you can read up more about the difference and how to leverage them in [our guide](examples.html#using-_rankinginfo).
-</td>
-</tr>
+ </tr>
  </tbody>
 </table>
 

diff --git a/docs/source/examples.html.md.erb b/docs/source/examples.html.md.erb
@@ -174,6 +174,18 @@ Then use this:
 
 ## Advanced
 
+### Dynamic control
+
+Using the `.configure` method, you can dynamically modify the behaviour of the Places search, to better tailor it to your users' need.
+
+For instance, if your service covers multiple countries or is available in multiple languages, you can dynamically modify Places configuration to better represent where your customer wants to search and in which language the results should be displayed.
+
+<%= partial '/partials/examples/dynamic_control', locals: config[:credentials][:documentation] %>
+
+```html
+<%= partial '/partials/examples/dynamic_control', locals: config[:credentials][:placeholder] %>
+```
+
 ### Places + Custom data
 
 Using [Algolia's autocomplete.js](https:/algolia/autocomplete.js) library, you can search in your own data along with showing Algolia Places results.

diff --git a/docs/source/partials/examples/_city_search.html.erb b/docs/source/partials/examples/_city_search.html.erb
@@ -7,13 +7,14 @@
  appId: '<%= app_id %>',
  apiKey: '<%= api_key %>',
  container: document.querySelector('#city'),
- type: 'city',
- aroundLatLngViaIP: false,
  templates: {
  value: function(suggestion) {
  return suggestion.name;
  }
  }
+ }).configure({
+ type: 'city',
+ aroundLatLngViaIP: false,
  });
 })();
 </script>
diff --git a/docs/source/partials/examples/_complete_form.html.erb b/docs/source/partials/examples/_complete_form.html.erb
@@ -24,12 +24,13 @@
  appId: '<%= app_id %>',
  apiKey: '<%= api_key %>',
  container: document.querySelector('#form-address'),
- type: 'address',
  templates: {
  value: function(suggestion) {
  return suggestion.name;
  }
  }
+ }).configure({
+ type: 'address'
  });
  placesAutocomplete.on('change', function resultSelected(e) {
  document.querySelector('#form-address2').value = e.suggestion.administrative || '';

diff --git a/docs/source/partials/examples/_country_search.html.erb b/docs/source/partials/examples/_country_search.html.erb
@@ -11,13 +11,14 @@
  appId: '<%= app_id %>',
  apiKey: '<%= api_key %>',
  container: document.querySelector('#country'),
- type: 'country',
  templates: {
  suggestion: function(suggestion) {
  return '<i class="flag ' + suggestion.countryCode + '"></i> ' +
  suggestion.highlight.name;
  }
  }
+ }).configure({
+ type: 'country',
  });
 })();
 </script>