Skip to content
This repository was archived by the owner on Feb 2, 2023. It is now read-only.

Commit 618149a

Browse files
author
vvo
committed
feat(various): multiple additions
Doc: - always use lib_places so that the examples are working locally with local places.js - create templates option (templates.inputValue, templates.dropdownSuggestion) - add templates example - add styling examples (input, dropdown) - add styling paragraph in doc - small fix on documentation getting started - add country icon (working) - add public transport icon (waiting for type=railway)
1 parent 2ca69b8 commit 618149a

19 files changed

+259
-48
lines changed

‎docs/config.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@
6565
###
6666

6767
config[:places_lib_version] = ENV['VERSION']
68-
config[:places_cdn_url] = '//cdn.jsdelivr.net/places.js/0/places.min.js'
68+
config[:places_cdn_url] = 'https://cdn.jsdelivr.net/places.js/0/places.min.js'
6969

7070
helpers do
7171
def nav_active(path)

‎docs/source/javascripts/index.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ placesAutocomplete.on('change', function(e) {
3434
$response.textContent = '';
3535
$response.classList.remove('display');
3636
} else {
37-
$response.textContent = JSON.stringify(e, '', 2);
37+
$response.textContent = JSON.stringify(e, null, 2);
3838
$response.classList.add('display');
3939
}
4040
});

‎docs/source/partials/documentation.md.erb‎

Lines changed: 83 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,15 @@
33
To use Algolia Places, all you need is an `<input />` and some JavaScript code that will load
44
and use the places.js library.
55

6-
### Using `<script>` tags
6+
### CDN `<script>`
7+
8+
Our JavaScript library is available on the [jsDelivr CDN](http://www.jsdelivr.com/projects/places.js).
9+
10+
```html
11+
<%= javascript_include_tag config[:places_cdn_url] %>
12+
```
13+
14+
Here's a small example using it:
715
816
```html
917
<input type="search" id="address-input" placeholder="Where are we going?" />
@@ -16,7 +24,9 @@ and use the places.js library.
1624
</script>
1725
```
1826

19-
### With npm
27+
### Using npm
28+
29+
Algolia Places is also available on [npm](https://www.npmjs.com/package/places.js).
2030

2131
Install the module:
2232

@@ -106,6 +116,29 @@ Change the countries to search in. You must pass an array of two letters country
106116
</tr>
107117
<tr>
108118
<td markdown="1">
119+
`templates`
120+
121+
Type: Object
122+
123+
required: no
124+
</td>
125+
<td markdown="1">
126+
Change the templates used in place.js.
127+
128+
Available templates:
129+
130+
- inputValue
131+
- dropdownSuggestion
132+
133+
Each template is a function that will receive a [suggestion object](#suggestion-object) and must return
134+
a `string`.
135+
136+
`inputValue` must return a plain string as it's used to fill the `input.value`. `dropdownSuggestion` can
137+
return an HTML string to be displayed in the dropdown.
138+
</td>
139+
</tr>
140+
<tr>
141+
<td markdown="1">
109142
`type`
110143

111144
Type: string
@@ -247,7 +280,13 @@ All of the events will send suggestion objects with those properties:
247280
Type: string
248281
</td>
249282
<td markdown="1">
250-
FIXME.
283+
Administrative region depending on the country.
284+
285+
Examples:
286+
287+
- Pays de la Loire
288+
- Texas
289+
- Catalunya
251290
</td>
252291
</tr>
253292
<tr>
@@ -311,8 +350,8 @@ Display name of the place found.
311350

312351
Examples:
313352

314-
- Paris
315-
- 589 Howard Street San Francisco
353+
- Paris
354+
- 589 Howard Street San Francisco
316355
</td>
317356
</tr>
318357
<tr>
@@ -326,8 +365,8 @@ Postcode (or ZIP Code) of the place found.
326365

327366
Examples:
328367

329-
- 94230
330-
- 1001
368+
- 94230
369+
- 1001
331370
</td>
332371
</tr>
333372
<tr>
@@ -341,13 +380,48 @@ Full display name of the place found. It's the value displayed in the input.
341380

342381
Examples:
343382

344-
- Paris Île-de-France, France
345-
- 589 Howard Street San Francisco, California, United States of America
383+
- Paris Île-de-France, France
384+
- 589 Howard Street San Francisco, California, United States of America
346385
</td>
347386
</tr>
348387
</tbody>
349388
</table>
350389

390+
## Styling
391+
392+
Algolia Places can fit existing designs. By default only the dropdown has a default light style.
393+
394+
The overall html structure looks like this:
395+
396+
```html
397+
<span class="algolia-places">
398+
<input class="ap-input" />
399+
<button type="button" class="ap-input-icon ap-input-icon-clear"><svg></svg></button>
400+
<button type="button" class="ap-input-icon ap-input-icon-pin"><svg></svg></button>
401+
</span>
402+
```
403+
404+
Then the dropdown html structure looks like this:
405+
406+
```html
407+
<span class="ap-dropdown-menu">
408+
<div>
409+
<span class="ap-suggestions">
410+
<div class="ap-suggestion">
411+
<span class="ap-suggestion-icon"><svg></svg></span>
412+
<span class="ap-name"></span>
413+
<span class="ap-address"></span>
414+
</div>
415+
<!-- Other suggestions -->
416+
</span>
417+
</div>
418+
</span>
419+
```
420+
421+
You can disable all the Algolia Places styling by passing the `style: false` option.
422+
423+
See our [styling examples](./examples.html#input-styling).
424+
351425
## Rate limits
352426

353427
Algolia Places enforces a default limit of **1,000 requests per hour and per IP** for free usage. You can contact us by <a href="mailto:support@algolia.com">e-mail</a> if you need more.

‎docs/source/partials/examples/_city_search.html.erb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<input type="search" id="city" class="form-control" placeholder="In which city do you live?" />
22

3-
<%= javascript_include_tag config[:places_cdn_url] %>
3+
<%= javascript_include_tag config[:places_lib_url] %>
44
<script>
55
var placesAutocomplete = places({
66
container: document.querySelector('#city'),

‎docs/source/partials/examples/_complete_form.html.erb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
</div>
1818
</form>
1919

20-
<%= javascript_include_tag config[:places_cdn_url] %>
20+
<%= javascript_include_tag config[:places_lib_url] %>
2121
<script>
2222
var placesAutocomplete = places({
2323
container: document.querySelector('#form-address'),

‎docs/source/partials/examples/_country_search.html.erb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<input type="search" id="country" class="form-control" placeholder="What's your favorite country?" />
22

3-
<%= javascript_include_tag config[:places_cdn_url] %>
3+
<%= javascript_include_tag config[:places_lib_url] %>
44
<script>
55
var placesAutocomplete = places({
66
container: document.querySelector('#country'),

‎docs/source/partials/examples/_full_styling.html.erb‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<div id="full-styling-address">
2+
<input type="search" placeholder="Where are we going?" />
3+
</div>
4+
5+
<%= javascript_include_tag config[:places_lib_url] %>
6+
<style>
7+
#full-styling-address .ap-dropdown-menu {
8+
background: #efefef;
9+
}
10+
11+
#full-styling-address .ap-dropdown-menu {
12+
background: #efefef;
13+
}
14+
</style>
15+
16+
<script>
17+
var placesAutocomplete = places({
18+
container: document.querySelector('#full-styling-address input'),
19+
style: false
20+
});
21+
</script>

‎docs/source/partials/examples/_index.md.erb‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,3 +51,42 @@ display the places.js results on the map and update them when needed.
5151
```html
5252
<%= partial '/partials/examples/map' %>
5353
```
54+
55+
## Custom templates
56+
57+
You can customize both the input value and dropdown suggestion templates.
58+
59+
Templates are functions called with a [suggestion object](./documentation.html#suggestion-object).
60+
61+
<%= partial '/partials/examples/templates' %>
62+
63+
```html
64+
<%= partial '/partials/examples/templates' %>
65+
```
66+
67+
## Input styling
68+
69+
The default Algolia Places styling should be sufficient for most websites: we only style
70+
the dropdown in a light way, the input remains unstyled and so can fit any website.
71+
72+
Here's an example styling the input:
73+
74+
<%= partial '/partials/examples/input_styling' %>
75+
76+
```html
77+
<%= partial '/partials/examples/input_styling' %>
78+
```
79+
80+
See our [documentation about styling](./documentation.html#styling) for more details.
81+
82+
## Full styling
83+
84+
To disable all styling, use the `style` option:
85+
86+
<%= partial '/partials/examples/full_styling' %>
87+
88+
```html
89+
<%= partial '/partials/examples/full_styling' %>
90+
```
91+
92+
See our [documentation about styling](./documentation.html#styling) for more details.

‎docs/source/partials/examples/_input_styling.html.erb‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<input type="search" id="input-styling-address" placeholder="Where are we going?" />
2+
3+
<%= javascript_include_tag config[:places_lib_url] %>
4+
<style>
5+
#input-styling-address {
6+
background: #efefef;
7+
color: #000;
8+
border: 3px solid #00f;
9+
border-radius: 1em;
10+
padding: .5em;
11+
}
12+
</style>
13+
14+
<script>
15+
var placesAutocomplete = places({
16+
container: document.querySelector('#input-styling-address')
17+
});
18+
</script>

‎docs/source/partials/examples/_map.html.erb‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
1-
<link rel="stylesheet" href="//cdn.jsdelivr.net/leaflet/1/leaflet.css" />
2-
<script src="//cdn.jsdelivr.net/leaflet/1/leaflet.js"></script>
1+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/leaflet/1/leaflet.css" />
2+
<script src="https://cdn.jsdelivr.net/leaflet/1/leaflet.js"></script>
33
<div id="map-example-container"></div>
44
<input type="search" id="input-map" class="form-control" placeholder="Where are we going?" />
55

66
<style>
77
#map-example-container {height: 300px};
88
</style>
99

10-
<%= javascript_include_tag config[:places_cdn_url] %>
10+
<%= javascript_include_tag config[:places_lib_url] %>
1111
<script>
1212
var placesAutocomplete = places({
1313
container: document.querySelector('#input-map'),

0 commit comments

Comments
 (0)