Skip to content

Commit 7939bc0

Browse files
mbehrlichjelbourn
authored and
mmalerba
committed
docs(google-maps): Improve documentation for Google Maps. (#20492)
* docs(google-maps): Improve documentation for Google Maps. Add new Google Maps components to documentation, including MapPolygon, MapPolyline, MapRectangle, MapCircle, MapGroundOverlay, MapKmlLayer, MapTransitLayer, MapTrafficLayer, and MapBicyclingLayer. Add instructions on how to lazy load the Google Maps JavaScript API for use with the @angular/google-maps components. * Apply suggestions from code review Co-authored-by: Jeremy Elbourn <jelbourn@gmail.com> Co-authored-by: Jeremy Elbourn <jelbourn@gmail.com> (cherry picked from commit 541c942)
1 parent 2f92689 commit 7939bc0

File tree

13 files changed

+529
-78
lines changed

13 files changed

+529
-78
lines changed

‎src/google-maps/README.md

Lines changed: 88 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -14,109 +14,119 @@ To install, run `npm install @angular/google-maps`.
1414
- Load the [Google Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/tutorial#Loading_the_Maps_API).
1515
- The Google Maps JavaScript API must be loaded before the `GoogleMap` component.
1616

17-
## GoogleMap
18-
19-
The `GoogleMap` component wraps the [`google.maps.Map` class](https://developers.google.com/maps/documentation/javascript/reference/map) from the Google Maps JavaScript API. You can configure the map via the component's inputs. The `options` input accepts a full [`google.maps.MapOptions` object](https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions), and the component additionally offers convenience inputs for setting the `center` and `zoom` of the map without needing an entire `google.maps.MapOptions` object. The `height` and `width` inputs accept a string to set the size of the Google map. [Events](https://developers.google.com/maps/documentation/javascript/reference/map#Map.bounds_changed) can be bound using the outputs of the `GoogleMap` component, although events have the same name as native mouse events (e.g. `mouseenter`) have been prefixed with "map" as to not collide with the native mouse events. Other members on the `google.maps.Map` object are available on the `GoogleMap` component and can be accessed using the [`ViewChild` decorator](https://angular.io/api/core/ViewChild).
20-
21-
See the [example](#example) below or the [source](./google-map/google-map.ts) to read the API.
22-
23-
## MapMarker
24-
25-
The `MapMarker` component wraps the [`google.maps.Marker` class](https://developers.google.com/maps/documentation/javascript/reference/marker#Marker) from the Google Maps JavaScript API. The `MapMarker` component displays a marker on the map when it is a content child of a `GoogleMap` component. Like `GoogleMap`, this component offers an `options` input as well as convenience inputs for `position`, `title`, `label`, and `clickable`, and supports all `google.maps.Marker` events as outputs.
26-
27-
See the [example](#example) below or the [source](./map-marker/map-marker.ts) to read the API.
28-
29-
## MapInfoWindow
30-
31-
The `MapInfoWindow` component wraps the [`google.maps.InfoWindow` class](https://developers.google.com/maps/documentation/javascript/reference/info-window#InfoWindow) from the Google Maps JavaScript API. The `MapInfoWindow` has a `options` input as well as a convenience `position` input. Content for the `MapInfoWindow` is the inner HTML of the component, and will keep the structure and css styling of any content that is put there when it is displayed as an info window on the map.
32-
33-
To display the `MapInfoWindow`, it must be a child of a `GoogleMap` component, and it must have its `open` method called, so a reference to `MapInfoWindow` will need to be loaded using the [`ViewChild` decorator](https://angular.io/api/core/ViewChild). The `open` method accepts an `MapMarker` as an optional input, if you want to anchor the `MapInfoWindow` to a `MapMarker`.
17+
```html
18+
<!-- index.html -->
19+
<!doctype html>
20+
<head>
21+
...
22+
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY">
23+
</script>
24+
</head>
25+
```
3426

35-
See the [example](#example) below or the [source](./map-info-window/map-info-window.ts) to read the API.
27+
## Lazy Loading the API
3628

37-
## Example
29+
The API can be loaded when the component is actually used by using the Angular HttpClient jsonp method to make sure that the component doesn't load until after the API has loaded.
3830

3931
```typescript
40-
// example-module.ts
32+
// google-maps-demo.module.ts
4133

42-
import {CommonModule} from '@angular/common';
43-
import {NgModule} from '@angular/core';
44-
import {GoogleMapsModule} from '@angular/google-maps';
34+
import { NgModule } from '@angular/core';
35+
import { GoogleMapsModule } from '@angular/google-maps';
36+
import { CommonModule } from '@angular/common';
37+
import { HttpClientModule, HttpClientJsonpModule } from '@angular/common/http';
4538

46-
import {GoogleMapDemo} from './google-map-demo';
39+
import { GoogleMapsDemoComponent } from './google-maps-demo.component';
4740

4841
@NgModule({
42+
declarations: [
43+
GoogleMapsDemoComponent,
44+
],
4945
imports: [
5046
CommonModule,
5147
GoogleMapsModule,
48+
HttpClientModule,
49+
HttpClientJsonpModule,
50+
],
51+
exports: [
52+
GoogleMapsDemoComponent,
5253
],
53-
declarations: [GoogleMapDemo],
5454
})
55-
export class GoogleMapDemoModule {
56-
}
55+
export class GoogleMapsDemoModule {}
56+
5757

58+
// google-maps-demo.component.ts
5859

59-
// example-app.ts
60-
import {Component, ViewChild} from '@angular/core';
61-
import {MapInfoWindow, MapMarker} from '@angular/google-maps';
60+
import { Component } from '@angular/core';
61+
import { HttpClient } from '@angular/common/http';
62+
import { Observable, of } from 'rxjs';
63+
import { catchError, map } from 'rxjs/operators';
6264

63-
/** Demo Component for @angular/google-maps/map */
6465
@Component({
65-
selector: 'google-map-demo',
66-
templateUrl: 'google-map-demo.html',
66+
selector: 'google-maps-demo',
67+
templateUrl: './google-maps-demo.component.html',
6768
})
68-
export class GoogleMapDemo {
69-
@ViewChild(MapInfoWindow) infoWindow: MapInfoWindow;
69+
export class GoogleMapsDemoComponent {
70+
apiLoaded: Observable<boolean>;
71+
72+
constructor(httpClient: HttpClient) {
73+
this.apiLoaded = httpClient.jsonp('https://maps.googleapis.com/maps/api/js?key=YOUR_KEY_HERE', 'callback')
74+
.pipe(
75+
map(() => true),
76+
catchError(() => of(false)),
77+
);
78+
}
79+
}
80+
```
7081

71-
center = {lat: 24, lng: 12};
72-
markerOptions = {draggable: false};
73-
markerPositions: google.maps.LatLngLiteral[] = [];
74-
zoom = 4;
75-
display?: google.maps.LatLngLiteral;
82+
```html
83+
<!-- google-maps-demo.component.html -->
7684

77-
addMarker(event: google.maps.MouseEvent) {
78-
this.markerPositions.push(event.latLng.toJSON());
79-
}
85+
<div *ngIf="apiLoaded | async">
86+
<google-map></google-map>
87+
</div>
88+
```
8089

81-
move(event: google.maps.MouseEvent) {
82-
this.display = event.latLng.toJSON();
83-
}
90+
## Components
8491

85-
openInfoWindow(marker: MapMarker) {
86-
this.infoWindow.open(marker);
87-
}
92+
- [`GoogleMap`](./google-map/README.md)
93+
- [`MapMarker`](./map-marker/README.md)
94+
- [`MapInfoWindow`](./map-info-window/README.md)
95+
- [`MapPolyline`](./map-polyline/README.md)
96+
- [`MapPolygon`](./map-polygon/README.md)
97+
- [`MapRectangle`](./map-rectangle/README.md)
98+
- [`MapCircle`](./map-circle/README.md)
99+
- [`MapGroundOverlay`](./map-ground-overlay/README.md)
100+
- [`MapKmlLayer`](./map-kml-layer/README.md)
101+
- [`MapTrafficLayer`](./map-traffic-layer/README.md)
102+
- [`MapTransitLayer`](./map-transit-layer/README.md)
103+
- [`MapBicyclingLayer`](./map-bicycling-layer/README.md)
88104

89-
removeLastMarker() {
90-
this.markerPositions.pop();
91-
}
92-
}
105+
## The Options Input
106+
107+
The Google Maps components implement all of the options for their respective objects from the Google Maps JavaScript API through an `options` input, but they also have specific inputs for some of the most common options. For example, the Google Maps component could have its options set either in with a google.maps.MapOptions object:
108+
109+
```html
110+
<google-map [options]="options"></google-map>
111+
```
112+
113+
```typescript
114+
options: google.maps.MapOptions = {
115+
center: {lat: 40, lng: -20},
116+
zoom: 4
117+
};
93118
```
94119

120+
It can also have individual options set for some of the most common options:
121+
95122
```html
96-
<!-- index.html -->
97-
<!doctype html>
98-
<head>
99-
...
100-
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY">
101-
</script>
102-
</head>
123+
<google-map [center]="center"
124+
[zoom]="zoom"></google-map>
125+
```
103126

104-
<!-- example-app.html -->
105-
<google-map height="400px"
106-
width="750px"
107-
[center]="center"
108-
[zoom]="zoom"
109-
(mapClick)="addMarker($event)"
110-
(mapMousemove)="move($event)"
111-
(mapRightclick)="removeLastMarker()">
112-
<map-marker #marker="mapMarker"
113-
*ngFor="let markerPosition of markerPositions"
114-
[position]="markerPosition"
115-
[options]="markerOptions"
116-
(mapClick)="openInfoWindow(marker)"></map-marker>
117-
<map-info-window>Info Window content</map-info-window>
118-
</google-map>
119-
120-
<div>Latitude: {{display?.lat}}</div>
121-
<div>Longitude: {{display?.lng}}</div>
127+
```typescript
128+
center: google.maps.LatLngLiteral = {lat: 40, lng: -20};
129+
zoom = 4;
122130
```
131+
132+
Not every option has its own input. See the API for each component to see if the option has a dedicated input or if it should be set in the options input.

‎src/google-maps/google-map/README.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# GoogleMap
2+
3+
The `GoogleMap` component wraps the [`google.maps.Map` class](https://developers.google.com/maps/documentation/javascript/reference/map) from the Google Maps JavaScript API. You can configure the map via the component's inputs. The `options` input accepts a full [`google.maps.MapOptions` object](https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions), and the component additionally offers convenience inputs for setting the `center` and `zoom` of the map without needing an entire `google.maps.MapOptions` object. The `height` and `width` inputs accept a string to set the size of the Google map. [Events](https://developers.google.com/maps/documentation/javascript/reference/map#Map.bounds_changed) can be bound using the outputs of the `GoogleMap` component, although events have the same name as native mouse events (e.g. `mouseenter`) have been prefixed with "map" as to not collide with the native mouse events. Other members on the `google.maps.Map` object are available on the `GoogleMap` component and can be accessed using the [`ViewChild` decorator](https://angular.io/api/core/ViewChild).
4+
5+
## Example
6+
7+
```typescript
8+
// google-maps-demo.module.ts
9+
10+
import {NgModule} from '@angular/core';
11+
import {GoogleMapsModule} from '@angular/google-maps';
12+
13+
import {GoogleMapDemo} from './google-map-demo';
14+
15+
@NgModule({
16+
imports: [
17+
GoogleMapsModule,
18+
],
19+
declarations: [GoogleMapDemo],
20+
})
21+
export class GoogleMapDemoModule {
22+
}
23+
24+
25+
// google-maps-demo.component.ts
26+
import {Component} from '@angular/core';
27+
28+
@Component({
29+
selector: 'google-map-demo',
30+
templateUrl: 'google-map-demo.html',
31+
})
32+
export class GoogleMapDemo {
33+
34+
center: google.maps.LatLngLiteral = {lat: 24, lng: 12};
35+
zoom = 4;
36+
37+
moveMap(event: google.maps.MouseEvent) {
38+
this.center = (event.latLng.toJSON());
39+
}
40+
41+
move(event: google.maps.MouseEvent) {
42+
this.display = event.latLng.toJSON();
43+
}
44+
}
45+
```
46+
47+
```html
48+
<!-- google-maps-demo.component.html -->
49+
<google-map height="400px"
50+
width="750px"
51+
[center]="center"
52+
[zoom]="zoom"
53+
(mapClick)="moveMap($event)"
54+
(mapMousemove)="move($event)">
55+
</google-map>
56+
57+
<div>Latitude: {{display?.lat}}</div>
58+
<div>Longitude: {{display?.lng}}</div>
59+
```

‎src/google-maps/map-bicycling-layer/README.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# MapBicyclingLayer
2+
3+
The `MapBicyclingLayer` component wraps the [`google.maps.BicyclingLayer` class](https://developers.google.com/maps/documentation/javascript/reference/map#BicyclingLayer) from the Google Maps JavaScript API.
4+
5+
## Example
6+
7+
```typescript
8+
// google-maps-demo.component.ts
9+
import {Component} from '@angular/core';
10+
11+
@Component({
12+
selector: 'google-map-demo',
13+
templateUrl: 'google-map-demo.html',
14+
})
15+
export class GoogleMapDemo {
16+
center: google.maps.LatLngLiteral = {lat: 24, lng: 12};
17+
zoom = 4;
18+
}
19+
```
20+
21+
```html
22+
<!-- google-maps-demo.component.html -->
23+
<google-map height="400px"
24+
width="750px"
25+
[center]="center"
26+
[zoom]="zoom">
27+
<map-bicycling-layer></map-bicycling-layer>
28+
</google-map>
29+
```

‎src/google-maps/map-circle/README.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# MapCircle
2+
3+
The `MapCircle` component wraps the [`google.maps.Circle` class](https://developers.google.com/maps/documentation/javascript/reference/polygon#Circle) from the Google Maps JavaScript API.
4+
5+
## Example
6+
7+
```typescript
8+
// google-maps-demo.component.ts
9+
import {Component} from '@angular/core';
10+
11+
@Component({
12+
selector: 'google-map-demo',
13+
templateUrl: 'google-map-demo.html',
14+
})
15+
export class GoogleMapDemo {
16+
center: google.maps.LatLngLiteral = {lat: 24, lng: 12};
17+
zoom = 4;
18+
19+
circleCenter: google.maps.LatLngLiteral = {lat: 10, lng: 15};
20+
radius: 3;
21+
}
22+
```
23+
24+
```html
25+
<!-- google-maps-demo.component.html -->
26+
<google-map height="400px"
27+
width="750px"
28+
[center]="center"
29+
[zoom]="zoom">
30+
<map-circle [center]="circleCenter"
31+
[radius]="radius"></map-circle>
32+
</google-map>
33+
```

‎src/google-maps/map-ground-overlay/README.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# MapGroundOverlay
2+
3+
The `MapGroundOverlay` component wraps the [`google.maps.BicyclingLayer` class](https://developers.google.com/maps/documentation/javascript/reference/image-overlay#GroundOverlay) from the Google Maps JavaScript API. A url and a bounds are required.
4+
5+
## Example
6+
7+
```typescript
8+
// google-maps-demo.component.ts
9+
import {Component} from '@angular/core';
10+
11+
@Component({
12+
selector: 'google-map-demo',
13+
templateUrl: 'google-map-demo.html',
14+
})
15+
export class GoogleMapDemo {
16+
center: google.maps.LatLngLiteral = {lat: 24, lng: 12};
17+
zoom = 4;
18+
19+
imageUrl = 'https://angular.io/assets/images/logos/angular/angular.svg';
20+
imageBounds: google.maps.LatLngBoundsLiteral = {
21+
east: 10,
22+
north: 10,
23+
south: -10,
24+
west: -10,
25+
};
26+
}
27+
```
28+
29+
```html
30+
<!-- google-maps-demo.component.html -->
31+
<google-map height="400px"
32+
width="750px"
33+
[center]="center"
34+
[zoom]="zoom">
35+
<map-ground-overlay [url]="imageUrl"
36+
[bounds]="imageBounds"></map-ground-overlay>
37+
</google-map>
38+
```

0 commit comments

Comments
 (0)