Skip to content

Commit 0092aeb

Browse files
dapriettdapriett
authored
Merge pull request #385 from fgutteridge/master
README.md grammar fixes, continuity maintenance, indentation fixes, etc.
2 parents ffd860b + b458e69 commit 0092aeb

File tree

1 file changed

+132
-117
lines changed

1 file changed

+132
-117
lines changed

‎README.md‎

Lines changed: 132 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
NativeScript plugin for Google Maps SDK
1+
NativeScript plugin for the Google Maps SDK
22
================
33

4-
This is a cross-platform (iOS & Android) Nativescript plugin for the [Google Maps API](https://developers.google.com/maps/)
4+
This is a cross-platform (iOS & Android) Nativescript plugin for the [Google Maps API](https://developers.google.com/maps/).
55

66
[![NPM version][npm-image]][npm-url]
77
[![Dependency status][david-dm-image]][david-dm-url]
@@ -15,68 +15,66 @@ This is a cross-platform (iOS & Android) Nativescript plugin for the [Google Map
1515

1616
Prerequisites
1717
===
18-
*iOS* - Cocoapods is [installed](https://guides.cocoapods.org/using/getting-started.html#getting-started)
18+
**iOS** - [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started) must be installed.
1919

20-
*Android* - Latest Google Play services SDK [installed](https://developer.android.com/sdk/installing/adding-packages.html)
20+
**Android** - The latest version of the [Google Play Services SDK](https://developer.android.com/sdk/installing/adding-packages.html) must be installed.
2121

22-
*Google Maps API Key* - Go to the [Google Developers Console](https://console.developers.google.com), create a project, and enable the `Google Maps Android API` and `Google Maps SDK for iOS` APIs. Then under credentials, create an API key.
22+
**Google Maps API Key** - Visit the [Google Developers Console](https://console.developers.google.com), create a project, and enable the `Google Maps Android API` and `Google Maps SDK for iOS` APIs. Then, under credentials, create an API key.
2323

2424
Installation
2525
===
2626

27-
## Install the plugin using the NativeScript CLI tooling
27+
Install the plugin using the NativeScript CLI tooling:
2828

2929
```
3030
tns plugin add nativescript-google-maps-sdk
3131
```
3232

33-
Setup Google Maps API
33+
Setup
3434
===
3535

3636
See demo code included [here](https://github.com/dapriett/nativescript-google-maps-sdk/tree/master/demo)
3737

38-
Live Demo [here](https://tinyurl.com/m7ndp7u)
38+
See a live demo [here](https://tinyurl.com/m7ndp7u)
3939

40-
## Setup Android API Key
41-
42-
40+
## Configure API Key for Android
4341

4442
### Nativescript < 4
4543

46-
First copy over the template string resource files for Android
44+
Start by copying the necessary template resource files in to the Android app resources folder:
4745

4846
```
4947
cp -r node_modules/nativescript-google-maps-sdk/platforms/android/res/values app/App_Resources/Android/
5048
```
51-
Next modify the file at `app/App_Resources/Android/values/nativescript_google_maps_api.xml`, uncomment `nativescript_google_maps_api_key` string and replace `PUT_API_KEY_HERE` with your api key.
49+
Next, modify your `app/App_Resources/Android/values/nativescript_google_maps_api.xml` file by uncommenting the `nativescript_google_maps_api_key` string, and replace `PUT_API_KEY_HERE` with the API key you created earlier.
5250

53-
Then, in your `AndroidManifest.xml` located at `app/App_Resources/Android/AndroidManifest.xml` insert into your `<application>` tags
51+
Finally, modify your `app/App_Resources/Android/AndroidManifest.xml` file by inserting the following in between the `<application>` tags:
5452

5553
```(xml)
5654
<meta-data
57-
android:name="com.google.android.geo.API_KEY"
58-
android:value="@string/nativescript_google_maps_api_key" />
55+
android:name="com.google.android.geo.API_KEY"
56+
android:value="@string/nativescript_google_maps_api_key" />
5957
```
6058

6159
### Nativescript 4+
6260

63-
First copy over the template string resource files for Android
61+
Start by copying the necessary template resource files in to the Android app resources folder:
6462

6563
```
6664
cp -r node_modules/nativescript-google-maps-sdk/platforms/android/res/values app/App_Resources/Android/src/main/res
6765
```
6866

69-
Next modify the file at `app/App_Resources/Android/src/main/res/values/nativescript_google_maps_api.xml`, uncomment `nativescript_google_maps_api_key` string and replace `PUT_API_KEY_HERE` with your api key.
67+
Next, modify your `app/App_Resources/Android/src/main/res/values/nativescript_google_maps_api.xml` file by uncommenting the `nativescript_google_maps_api_key` string, and replace `PUT_API_KEY_HERE` with the API key you created earlier.
7068

71-
Then, in your `AndroidManifest.xml` located at `app/App_Resources/Android/src/main/AndroidManifest.xml` insert into your `<application>` tags
69+
Finally, modify your `app/App_Resources/Android/src/main/AndroidManifest.xml` file by inserting the following in between your `<application>` tags:
7270

7371
```(xml)
7472
<meta-data
75-
android:name="com.google.android.geo.API_KEY"
76-
android:value="@string/nativescript_google_maps_api_key" />
73+
android:name="com.google.android.geo.API_KEY"
74+
android:value="@string/nativescript_google_maps_api_key" />
7775
```
7876

79-
The plugin will default to latest available version of the Android `play-services-maps` SDK. If you need to change the version, you can add a project ext property `googlePlayServicesVersion` like so:
77+
The plugin will default to the latest available version of the Google Play Services SDK for Android. If you need to change the version, you can add a `project.ext` property, `googlePlayServicesVersion`, like so:
8078

8179
```
8280
// /app/App_Resources/Android/app.gradle
@@ -86,105 +84,144 @@ project.ext {
8684
}
8785
```
8886

89-
## Setup iOS API Key
87+
## Configure API Key for iOS
9088

91-
In the main script of your app `app.js`, use the following to add the API key (providing your key in place of `PUT_API_KEY_HERE`)
89+
In your `app.js`, use the following code to add your API key (replace `PUT_API_KEY_HERE` with the API key you created earlier):
9290

9391
```
94-
if(application.ios) {
95-
GMSServices.provideAPIKey("PUT_API_KEY_HERE");
92+
if (application.ios) {
93+
GMSServices.provideAPIKey("PUT_API_KEY_HERE");
9694
}
9795
```
98-
If you are using Angular, you need to modify the `app.module.ts` as follows:
96+
If you are using Angular, modify your `app.module.ts` as follows:
9997
```
10098
import * as platform from "platform";
10199
declare var GMSServices: any;
100+
102101
....
102+
103103
if (platform.isIOS) {
104-
GMSServices.provideAPIKey("PUT_API_KEY_HERE");
104+
GMSServices.provideAPIKey("PUT_API_KEY_HERE");
105105
}
106106
```
107107

108108
## Adding the MapView
109109

110-
Modify your view by adding the namespace `xmlns:maps="nativescript-google-maps-sdk"` to your page, then using the `<maps:mapView />` tag to create the MapView.
110+
Modify your view by adding the `xmlns:maps="nativescript-google-maps-sdk"` namespace to your `<Page>` tag, then use the `<maps:mapView />` tag to create the MapView:
111111

112112
```
113-
<!-- /app/main-page.xml -->
114-
<Page
115-
xmlns="http://www.nativescript.org/tns.xsd"
116-
xmlns:maps="nativescript-google-maps-sdk"
117-
>
118-
<GridLayout>
119-
<maps:mapView latitude="{{ latitude }}" longitude="{{ longitude }}" mapAnimationsEnabled="{{ mapAnimationsEnabled }}"
120-
zoom="{{ zoom }}" bearing="{{ bearing }}"
121-
tilt="{{ tilt }}" padding="{{ padding }}" mapReady="onMapReady"
122-
markerSelect="onMarkerSelect" markerBeginDragging="onMarkerBeginDragging"
123-
markerEndDragging="onMarkerEndDragging" markerDrag="onMarkerDrag"
124-
cameraChanged="onCameraChanged"
125-
cameraMove="onCameraMove" />
126-
</GridLayout>
113+
<!-- /app/main-page.xml -->
114+
115+
<Page
116+
xmlns="http://www.nativescript.org/tns.xsd"
117+
xmlns:maps="nativescript-google-maps-sdk"
118+
>
119+
<GridLayout>
120+
<maps:mapView
121+
latitude="{{ latitude }}"
122+
longitude="{{ longitude }}"
123+
zoom="{{ zoom }}"
124+
bearing="{{ bearing }}"
125+
tilt="{{ tilt }}"
126+
mapAnimationsEnabled="{{ mapAnimationsEnabled }}"
127+
padding="{{ padding }}"
128+
mapReady="onMapReady"
129+
markerSelect="onMarkerSelect"
130+
markerBeginDragging="onMarkerBeginDragging"
131+
markerEndDragging="onMarkerEndDragging"
132+
markerDrag="onMarkerDrag"
133+
cameraChanged="onCameraChanged"
134+
cameraMove="onCameraMove"
135+
/>
136+
</GridLayout>
127137
</Page>
128138
```
129139

130140
## Properties
131141

132-
The following properties are available to you for adjusting camera view.
142+
The following properties are available for adjusting the camera view:
133143

134-
Property | Description
135-
-------------- |:---------------------------------
136-
`latitude` | number
137-
`longitude` | number
138-
`zoom` | number
139-
`bearing` | number
140-
`tilt` | number
141-
`padding` | array of numbers reflectig top, bottom, left and right paddings
142-
`mapAnimationsEnabled` | boolean of whether to animate camera changes
144+
| Property | Description and Data Type
145+
:------------- | :---------------------------------
146+
`latitude` | Latitude, in degrees: `number`
147+
`longitude` | Longitude, in degrees: `number`
148+
`zoom` | Zoom level (described [here](https://developers.google.com/maps/documentation/javascript/tutorial#zoom-levels)): `number`
149+
`bearing` | Bearing, in degrees: `number`
150+
`tilt` | Tilt, in degrees: `number`
151+
`padding` | Top, bottom, left and right padding amounts, in Device Independent Pixels: `number[]` (array)
152+
`mapAnimationsEnabled` | Whether or not to animate camera changes: `Boolean`
143153

144154
## Events
145155

146156
The following events are available:
147157

148-
Event | Description
149-
-------------- |:---------------------------------
150-
`mapReady` | Called when Google Map is ready for use
151-
`coordinateTapped` | Fires when coordinate is clicked on map
152-
`coordinateLongPress` | Fires when coordinate is "long pressed"
153-
`markerSelect` | Fires whenever a marker is selected
154-
`shapeSelect` | Fires whenever a shape (`Circle`, `Polygon`, `Polyline`) is clicked. You must explicity configure `shape.clickable = true;` on your shapes.
158+
| Event | Description
159+
:------------- | :---------------------------------
160+
`mapReady` | Fires when the MapView is ready for use
161+
`coordinateTapped` | Fires when a coordinate is tapped on the map
162+
`coordinateLongPress` | Fires when a coordinate is long-pressed on the map
163+
`markerSelect` | Fires when a marker is selected
164+
`shapeSelect` | Fires when a shape (e.g., `Circle`, `Polygon`, `Polyline`) is selected *(Note: you must explicity configure `shape.clickable = true;` for this event to fire)*
155165
`markerBeginDragging` | Fires when a marker begins dragging
156-
`markerDrag` | Fires repeatedly while a marker is being dragged
157166
`markerEndDragging` | Fires when a marker ends dragging
158-
`markerInfoWindowTapped` | Fired on tapping Marker Info Window
159-
`myLocationTapped` | Fired when the 'My Location' button is tapped
160-
`cameraChanged` | Fired after the camera has changed
161-
`cameraMove` | Fired while the camera is moving
167+
`markerDrag` | Fires repeatedly while a marker is being dragged
168+
`myLocationTapped` | Fires when the 'My Location' button is tapped
169+
`markerInfoWindowTapped` | Fires when a marker's info window is tapped
170+
`cameraChanged` | Fires after the camera has changed
171+
`cameraMove` | Fires repeatedly while the camera is moving
172+
173+
## Native Map Object
174+
175+
The MapView's `gMap` property gives you access to the platform's native map object–––consult the appropriate SDK reference on how to use it: [iOS](https://developers.google.com/maps/documentation/ios-sdk/reference/interface_g_m_s_map_view) | [Android](https://developers.google.com/android/reference/com/google/android/gms/maps/GoogleMap)
176+
177+
## UI Settings
178+
179+
You can adjust the map's UI settings after the `mapReady` event has fired by configuring the following properties on `mapView.settings`:
162180

181+
| Property | Description and Data Type
182+
:--------------- |:---------------------------------
183+
`compassEnabled` | Whether the compass is enabled or not: `Boolean`
184+
`indoorLevelPickerEnabled` | Whether the indoor level picker is enabled or not: `Boolean`
185+
`mapToolbarEnabled` | ** **Android only** ** Whether the map toolbar is enabled or not: `Boolean`
186+
`myLocationButtonEnabled` | Whether the 'My Location' button is enabled or not: `Boolean`
187+
`rotateGesturesEnabled` | Whether the compass is enabled or not: `Boolean`
188+
`scrollGesturesEnabled` | Whether map scroll gestures are enabled or not: `Boolean`
189+
`tiltGesturesEnabled` | Whether map tilt gestures are enabled or not: `Boolean`
190+
`zoomGesturesEnabled` | Whether map zoom gestures are enabled or not: `Boolean`
191+
`zoomControlsEnabled` | ** **Android only** ** Whether map zoom controls are enabled or not: `Boolean`
163192

164-
The property `gMap` gives you access to the raw platform Map Object - see their SDK references for how to use them ( [iOS](https://developers.google.com/maps/documentation/ios-sdk/reference/interface_g_m_s_map_view) | [Android](https://developers.google.com/android/reference/com/google/android/gms/maps/GoogleMap) )
193+
## Styling
194+
195+
Use `gMap.setStyle(style);` to set the map's styling ([Google Maps Style Reference](https://developers.google.com/maps/documentation/android-api/style-reference) | [Styling Wizard](https://mapstyle.withgoogle.com/)).
196+
197+
### Angular
198+
199+
Use `this.mapView.setStyle(<Style>JSON.parse(this.styles));` inside of the `onMapReady` event handler. In this example, `this.mapView` is the `MapView` object and `this.styles` is a reference to a JSON file that was created using the [Styling Wizard](https://mapstyle.withgoogle.com/). The `<Style>` type was imported from the plugin as `{ Style }`.
200+
201+
## Basic Example
165202

166203
```
167204
// /app/main-page.js
168205
169206
var mapsModule = require("nativescript-google-maps-sdk");
170207
171208
function onMapReady(args) {
172-
var mapView = args.object;
173-
174-
console.log("Setting a marker...");
175-
var marker = new mapsModule.Marker();
176-
marker.position = mapsModule.Position.positionFromLatLng(-33.86, 151.20);
177-
marker.title = "Sydney";
178-
marker.snippet = "Australia";
179-
marker.userData = { index : 1};
180-
mapView.addMarker(marker);
181-
182-
// Disabling zoom gestures
183-
mapView.settings.zoomGesturesEnabled = false;
209+
var mapView = args.object;
210+
211+
console.log("Setting a marker...");
212+
var marker = new mapsModule.Marker();
213+
marker.position = mapsModule.Position.positionFromLatLng(-33.86, 151.20);
214+
marker.title = "Sydney";
215+
marker.snippet = "Australia";
216+
marker.userData = { index : 1};
217+
mapView.addMarker(marker);
218+
219+
// Disabling zoom gestures
220+
mapView.settings.zoomGesturesEnabled = false;
184221
}
185222
186223
function onMarkerSelect(args) {
187-
console.log("Clicked on " +args.marker.title);
224+
console.log("Clicked on " +args.marker.title);
188225
}
189226
190227
function onCameraChanged(args) {
@@ -201,40 +238,16 @@ exports.onCameraChanged = onCameraChanged;
201238
exports.onCameraMove = onCameraMove;
202239
```
203240

204-
## UI Settings
205-
206-
You can adjust the Map UI settings after mapReady by changing the below properties on `mapView.settings`
207-
208-
Property | Description
209-
-------------- |:---------------------------------
210-
`compassEnabled` | boolean - Whether the compass is enabled/disabled
211-
`indoorLevelPickerEnabled` | boolean - Whether the indoor level picker is enabled/disabled
212-
`mapToolbarEnabled` | boolean - Whether the indoor level picker is enabled/disabled ** ****Android only**** **
213-
`myLocationButtonEnabled` | boolean - Whether the 'My Location' button is enabled/disabled
214-
`rotateGesturesEnabled` | boolean - Whether the compass is enabled/disabled
215-
`scrollGesturesEnabled` | boolean - Whether scroll gestures are enabled/disabled
216-
`tiltGesturesEnabled` | boolean - Whether tilt gestures are enabled/disabled
217-
`zoomControlsEnabled` | boolean - Whether the zoom controls are enabled/disabled ** ****Android only**** **
218-
`zoomGesturesEnabled` | boolean - Whether zoom gestures are enabled/disabled
219-
220-
221-
## Styling
222-
Use `gMap.setStyle(style);` to change the map styling.
223-
224-
For Angular map styling, use `this.mapView.setStyle(<Style>JSON.parse(this.styles));` inside of the `onMapReady` function. In this example `this.mapView` is the imported `MapView` from the plugin and `this.styles` is a reference to a json file that was created using the link below. The `<Style>` was also imported from the plugin as `{ Style }`.
225-
226-
For map styles, see [Google Maps Style Reference](https://developers.google.com/maps/documentation/android-api/style-reference) and the [Styling Wizard](https://mapstyle.withgoogle.com/).
227-
228241
## Custom Info Windows (Beta)
229242

230-
To customize the marker info windows, define a template in your view like so:
243+
To use custom marker info windows, define a template in your view like so:
231244

232245
```
233-
<!-- /app/main-page.xml -->
234-
<Page
235-
xmlns="http://www.nativescript.org/tns.xsd"
236-
xmlns:maps="nativescript-google-maps-sdk"
237-
>
246+
<!-- /app/main-page.xml -->
247+
<Page
248+
xmlns="http://www.nativescript.org/tns.xsd"
249+
xmlns:maps="nativescript-google-maps-sdk"
250+
>
238251
<GridLayout>
239252
<maps:mapView mapReady="onMapReady">
240253
<!-- Default Info Window Template -->
@@ -260,20 +273,20 @@ To customize the marker info windows, define a template in your view like so:
260273
</Page>
261274
```
262275

263-
If a marker has the `infoWindowTemplate` property set like so:
276+
...and set the `infoWindowTemplate` property like so:
264277

265278
```
266279
var marker = new mapsModule.Marker();
267280
marker.infoWindowTemplate = 'testWindow';
268281
```
269282

270-
This will use the template with that key. If it's not set then it'll use the default custom template if set, overwise the standard info window.
283+
This will configure the marker to use the info window template with the given key. If no template with that key is found, then it will use the default info window template.
271284

272-
** *Known Issue* - External Images fail to show in iOS info windows (local Images work fine)
285+
** *Known issue:* remote images fail to display in iOS info windows (local images work fine)
273286

274-
## Using with Angular
287+
## Usage with Angular
275288

276-
See angular demo code included [here](https://github.com/dapriett/nativescript-google-maps-sdk/tree/master/ng-demo)
289+
See Angular demo code included [here](https://github.com/dapriett/nativescript-google-maps-sdk/tree/master/ng-demo)
277290

278291
```
279292
// /app/map-example.component.ts
@@ -304,14 +317,16 @@ export class MapExampleComponent {
304317
```
305318
# Angular 8 Support
306319

307-
If you are using Angular 8, there is a temporary change to the `@ViewChild` directive, this will not be needed in Angular 9.
320+
If you are using Angular 8, there is a temporary fix needed for the `@ViewChild` directive, and will not be needed in Angular 9:
308321

309-
For now use this instead: `@ViewChild("MapView", {static: false}) mapView: ElementRef;`
322+
```
323+
@ViewChild("MapView", {static: false}) mapView: ElementRef;
324+
```
310325

311326

312327
# Clustering Support (Issue [#57](https://github.com/dapriett/nativescript-google-maps-sdk/issues/57))
313328

314-
There is a seperate plugin in development thanks to [@naderio](https://github.com/naderio) - see [nativescript-google-maps-utils](https://github.com/naderio/nativescript-google-maps-utils)
329+
There is a seperate plugin in development thanks to [@naderio](https://github.com/naderio): see [nativescript-google-maps-utils](https://github.com/naderio/nativescript-google-maps-utils).
315330

316331
# Get Help
317332

0 commit comments

Comments
 (0)