From b2775d4a4cc0f7698dacdc98d36205d376a529bd Mon Sep 17 00:00:00 2001 From: Matthew Ehrlich Date: Thu, 3 Sep 2020 12:13:29 -0700 Subject: [PATCH 1/2] 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. --- src/google-maps/README.md | 166 ++++++++++-------- src/google-maps/google-map/README.md | 59 +++++++ src/google-maps/map-bicycling-layer/README.md | 29 +++ src/google-maps/map-circle/README.md | 33 ++++ src/google-maps/map-ground-overlay/README.md | 38 ++++ src/google-maps/map-info-window/README.md | 48 +++++ src/google-maps/map-kml-layer/README.md | 31 ++++ src/google-maps/map-marker/README.md | 39 ++++ src/google-maps/map-polygon/README.md | 35 ++++ src/google-maps/map-polyline/README.md | 35 ++++ src/google-maps/map-rectangle/README.md | 36 ++++ src/google-maps/map-traffic-layer/README.md | 29 +++ src/google-maps/map-transit-layer/README.md | 29 +++ 13 files changed, 529 insertions(+), 78 deletions(-) create mode 100644 src/google-maps/google-map/README.md create mode 100644 src/google-maps/map-bicycling-layer/README.md create mode 100644 src/google-maps/map-circle/README.md create mode 100644 src/google-maps/map-ground-overlay/README.md create mode 100644 src/google-maps/map-info-window/README.md create mode 100644 src/google-maps/map-kml-layer/README.md create mode 100644 src/google-maps/map-marker/README.md create mode 100644 src/google-maps/map-polygon/README.md create mode 100644 src/google-maps/map-polyline/README.md create mode 100644 src/google-maps/map-rectangle/README.md create mode 100644 src/google-maps/map-traffic-layer/README.md create mode 100644 src/google-maps/map-transit-layer/README.md diff --git a/src/google-maps/README.md b/src/google-maps/README.md index 7bc219f05044..d57e0faee1c2 100644 --- a/src/google-maps/README.md +++ b/src/google-maps/README.md @@ -14,109 +14,119 @@ To install, run `npm install @angular/google-maps`. - Load the [Google Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/tutorial#Loading_the_Maps_API). - The Google Maps JavaScript API must be loaded before the `GoogleMap` component. -## GoogleMap - -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). - -See the [example](#example) below or the [source](./google-map/google-map.ts) to read the API. - -## MapMarker - -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. - -See the [example](#example) below or the [source](./map-marker/map-marker.ts) to read the API. - -## MapInfoWindow - -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. - -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`. +```html + + + + ... + + +``` -See the [example](#example) below or the [source](./map-info-window/map-info-window.ts) to read the API. +## Lazy Loading the API -## Example +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. ```typescript -// example-module.ts +// google-maps-demo.module.ts -import {CommonModule} from '@angular/common'; -import {NgModule} from '@angular/core'; -import {GoogleMapsModule} from '@angular/google-maps'; +import { NgModule } from '@angular/core'; +import { GoogleMapsModule } from '@angular/google-maps'; +import { CommonModule } from '@angular/common'; +import { HttpClientModule, HttpClientJsonpModule } from '@angular/common/http'; -import {GoogleMapDemo} from './google-map-demo'; +import { GoogleMapsDemoComponent } from './google-maps-demo.component'; @NgModule({ + declarations: [ + GoogleMapsDemoComponent, + ], imports: [ CommonModule, GoogleMapsModule, + HttpClientModule, + HttpClientJsonpModule, + ], + exports: [ + GoogleMapsDemoComponent, ], - declarations: [GoogleMapDemo], }) -export class GoogleMapDemoModule { -} +export class GoogleMapsDemoModule {} + +// google-maps-demo.component.ts -// example-app.ts -import {Component, ViewChild} from '@angular/core'; -import {MapInfoWindow, MapMarker} from '@angular/google-maps'; +import { Component } from '@angular/core'; +import { HttpClient } from '@angular/common/http'; +import { Observable, of } from 'rxjs'; +import { catchError, map } from 'rxjs/operators'; -/** Demo Component for @angular/google-maps/map */ @Component({ - selector: 'google-map-demo', - templateUrl: 'google-map-demo.html', + selector: 'google-maps-demo', + templateUrl: './google-maps-demo.component.html', }) -export class GoogleMapDemo { - @ViewChild(MapInfoWindow) infoWindow: MapInfoWindow; +export class GoogleMapsDemoComponent { + apiLoaded: Observable; + + constructor(httpClient: HttpClient) { + this.apiLoaded = httpClient.jsonp('https://maps.googleapis.com/maps/api/js?key=YOUR_KEY_HERE', 'callback') + .pipe( + map(() => true), + catchError(() => of(false)), + ); + } +} +``` - center = {lat: 24, lng: 12}; - markerOptions = {draggable: false}; - markerPositions: google.maps.LatLngLiteral[] = []; - zoom = 4; - display?: google.maps.LatLngLiteral; +```html + - addMarker(event: google.maps.MouseEvent) { - this.markerPositions.push(event.latLng.toJSON()); - } +
+ +
+``` - move(event: google.maps.MouseEvent) { - this.display = event.latLng.toJSON(); - } +## Components - openInfoWindow(marker: MapMarker) { - this.infoWindow.open(marker); - } +- [`GoogleMap`](./google-map/README.md) +- [`MapMarker`](./map-marker/README.md) +- [`MapInfoWindow`](./map-info-window/README.md) +- [`MapPolyline`](./map-polyline/README.md) +- [`MapPolygon`](./map-polygon/README.md) +- [`MapRectangle`](./map-rectangle/README.md) +- [`MapCircle`](./map-circle/README.md) +- [`MapGroundOverlay`](./map-ground-overlay/README.md) +- [`MapKmlLayer`](./map-kml-layer/README.md) +- [`MapTrafficLayer`](./map-traffic-layer/README.md) +- [`MapTransitLayer`](./map-transit-layer/README.md) +- [`MapBicyclingLayer`](./map-bicycling-layer/README.md) - removeLastMarker() { - this.markerPositions.pop(); - } -} +## The Options Input + +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: + +```html + +``` + +```typescript +options: google.maps.MapOptions = { + center: {lat: 40, lng: -20}, + zoom: 4 +}; ``` +It can also have individual options set for some of the most common options: + ```html - - - - ... - - + +``` - - - - Info Window content - - -
Latitude: {{display?.lat}}
-
Longitude: {{display?.lng}}
+```typescript +center: google.maps.LatLngLiteral = {lat: 40, lng: -20}; +zoom = 4; ``` + +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. diff --git a/src/google-maps/google-map/README.md b/src/google-maps/google-map/README.md new file mode 100644 index 000000000000..02290caff544 --- /dev/null +++ b/src/google-maps/google-map/README.md @@ -0,0 +1,59 @@ +# GoogleMap + +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). + +## Example + +```typescript +// google-maps-demo.module.ts + +import {NgModule} from '@angular/core'; +import {GoogleMapsModule} from '@angular/google-maps'; + +import {GoogleMapDemo} from './google-map-demo'; + +@NgModule({ + imports: [ + GoogleMapsModule, + ], + declarations: [GoogleMapDemo], +}) +export class GoogleMapDemoModule { +} + + +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; + + moveMap(event: google.maps.MouseEvent) { + this.center = (event.latLng.toJSON()); + } + + move(event: google.maps.MouseEvent) { + this.display = event.latLng.toJSON(); + } +} +``` + +```html + + + + +
Latitude: {{display?.lat}}
+
Longitude: {{display?.lng}}
+``` diff --git a/src/google-maps/map-bicycling-layer/README.md b/src/google-maps/map-bicycling-layer/README.md new file mode 100644 index 000000000000..dc562836b9da --- /dev/null +++ b/src/google-maps/map-bicycling-layer/README.md @@ -0,0 +1,29 @@ +# MapBicyclingLayer + +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. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; +} +``` + +```html + + + + +``` diff --git a/src/google-maps/map-circle/README.md b/src/google-maps/map-circle/README.md new file mode 100644 index 000000000000..f73ccae95ebf --- /dev/null +++ b/src/google-maps/map-circle/README.md @@ -0,0 +1,33 @@ +# MapCircle + +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. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; + + circleCenter: google.maps.LatLngLiteral = {lat: 10, lng: 15}; + radius: 3; +} +``` + +```html + + + + +``` diff --git a/src/google-maps/map-ground-overlay/README.md b/src/google-maps/map-ground-overlay/README.md new file mode 100644 index 000000000000..19ebfe0ed3ee --- /dev/null +++ b/src/google-maps/map-ground-overlay/README.md @@ -0,0 +1,38 @@ +# MapGroundOverlay + +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. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; + + imageUrl = 'https://angular.io/assets/images/logos/angular/angular.svg'; + imageBounds: google.maps.LatLngBoundsLiteral = { + east: 10, + north: 10, + south: -10, + west: -10, + }; +} +``` + +```html + + + + +``` diff --git a/src/google-maps/map-info-window/README.md b/src/google-maps/map-info-window/README.md new file mode 100644 index 000000000000..2a67235cd116 --- /dev/null +++ b/src/google-maps/map-info-window/README.md @@ -0,0 +1,48 @@ +## MapInfoWindow + +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 an `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. + +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`. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component, ViewChild} from '@angular/core'; +import {MapInfoWindow, MapMarker} from '@angular/google-maps'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + @ViewChild(MapInfoWindow) infoWindow: MapInfoWindow; + + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + markerPositions: google.maps.LatLngLiteral[] = []; + zoom = 4; + + addMarker(event: google.maps.MouseEvent) { + this.markerPositions.push(event.latLng.toJSON()); + } + + openInfoWindow(marker: MapMarker) { + this.infoWindow.open(marker); + } +} +``` + +```html + + + + Info Window content + +``` diff --git a/src/google-maps/map-kml-layer/README.md b/src/google-maps/map-kml-layer/README.md new file mode 100644 index 000000000000..96ba65b44119 --- /dev/null +++ b/src/google-maps/map-kml-layer/README.md @@ -0,0 +1,31 @@ +# MapKmlLayer + +The `MapKmlLayer` component wraps the [`google.maps.KmlLayer` class](https://developers.google.com/maps/documentation/javascript/reference/kml#KmlLayer) from the Google Maps JavaScript API. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; + + kmlUrl = 'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml'; +} +``` + +```html + + + + +``` diff --git a/src/google-maps/map-marker/README.md b/src/google-maps/map-marker/README.md new file mode 100644 index 000000000000..17eae41759e7 --- /dev/null +++ b/src/google-maps/map-marker/README.md @@ -0,0 +1,39 @@ +# MapMarker + +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. + +## Example + +```typescript +// google-map-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; + markerOptions: google.maps.MarkerOptions = {draggable: false}; + markerPositions: google.maps.LatLngLiteral[] = []; + + addMarker(event: google.maps.MouseEvent) { + this.markerPositions.push(event.latLng.toJSON()); + } +} +``` + +```html + + + + +``` diff --git a/src/google-maps/map-polygon/README.md b/src/google-maps/map-polygon/README.md new file mode 100644 index 000000000000..000f29f9c86c --- /dev/null +++ b/src/google-maps/map-polygon/README.md @@ -0,0 +1,35 @@ +# MapPolygon + +The `MapPolygon` component wraps the [`google.maps.Polygon` class](https://developers.google.com/maps/documentation/javascript/reference/polygon#Polygon) from the Google Maps JavaScript API. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; + + vertices: google.maps.LatLngLiteral[] = [ + {lat: 13, lng: 13}, + {lat: -13, lng: 0}, + {lat: 13, lng: -13}, + ]; +} +``` + +```html + + + + +``` diff --git a/src/google-maps/map-polyline/README.md b/src/google-maps/map-polyline/README.md new file mode 100644 index 000000000000..0c2c7687d689 --- /dev/null +++ b/src/google-maps/map-polyline/README.md @@ -0,0 +1,35 @@ +# MapPolyline + +The `MapPolyline` component wraps the [`google.maps.Polyline` class](https://developers.google.com/maps/documentation/javascript/reference/polygon#Polyline) from the Google Maps JavaScript API. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; + + vertices: google.maps.LatLngLiteral[] = [ + {lat: 13, lng: 13}, + {lat: -13, lng: 0}, + {lat: 13, lng: -13}, + ]; +} +``` + +```html + + + + +``` diff --git a/src/google-maps/map-rectangle/README.md b/src/google-maps/map-rectangle/README.md new file mode 100644 index 000000000000..b74e53ef178a --- /dev/null +++ b/src/google-maps/map-rectangle/README.md @@ -0,0 +1,36 @@ +# MapRectangle + +The `MapRectangle` component wraps the [`google.maps.Rectangle` class](https://developers.google.com/maps/documentation/javascript/reference/polygon#Rectangle) from the Google Maps JavaScript API. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; + + bounds: google.maps.LatLngBoundsLiteral = { + east: 10, + north: 10, + south: -10, + west: -10, + }; +} +``` + +```html + + + + +``` diff --git a/src/google-maps/map-traffic-layer/README.md b/src/google-maps/map-traffic-layer/README.md new file mode 100644 index 000000000000..0b2bb33a70e9 --- /dev/null +++ b/src/google-maps/map-traffic-layer/README.md @@ -0,0 +1,29 @@ +# MapTrafficLayer + +The `MapTrafficLayer` component wraps the [`google.maps.TrafficLayer` class](https://developers.google.com/maps/documentation/javascript/reference/map#TrafficLayer) from the Google Maps JavaScript API. `autoRefresh` is true by default. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; +} +``` + +```html + + + + +``` diff --git a/src/google-maps/map-transit-layer/README.md b/src/google-maps/map-transit-layer/README.md new file mode 100644 index 000000000000..66d9c2707f11 --- /dev/null +++ b/src/google-maps/map-transit-layer/README.md @@ -0,0 +1,29 @@ +# MapTransitLayer + +The `MapTransitLayer` component wraps the [`google.maps.TransitLayer` class](https://developers.google.com/maps/documentation/javascript/reference/map#TransitLayer) from the Google Maps JavaScript API. + +## Example + +```typescript +// google-maps-demo.component.ts +import {Component} from '@angular/core'; + +@Component({ + selector: 'google-map-demo', + templateUrl: 'google-map-demo.html', +}) +export class GoogleMapDemo { + center: google.maps.LatLngLiteral = {lat: 24, lng: 12}; + zoom = 4; +} +``` + +```html + + + + +``` From 2c8cd329777bcb2521cdc4dcb415cab68166fb07 Mon Sep 17 00:00:00 2001 From: mbehrlich Date: Thu, 3 Sep 2020 14:07:23 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Jeremy Elbourn --- src/google-maps/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/google-maps/README.md b/src/google-maps/README.md index d57e0faee1c2..8c90cf1013b6 100644 --- a/src/google-maps/README.md +++ b/src/google-maps/README.md @@ -104,7 +104,7 @@ export class GoogleMapsDemoComponent { ## The Options Input -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: +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: ```html @@ -129,4 +129,4 @@ center: google.maps.LatLngLiteral = {lat: 40, lng: -20}; zoom = 4; ``` -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. +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.