Skip to content

Commit 667d45d

Browse files
fgutteridgefgutteridge
authored
README.md cleanup and cosmetic changes
Grammar fixes, styling maintenance (for continuity), fixed indentation, etc.
1 parent a125929 commit 667d45d

File tree

1 file changed

+125
-113
lines changed

1 file changed

+125
-113
lines changed

‎README.md‎

Lines changed: 125 additions & 113 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,16 +84,16 @@ 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) {
92+
if (application.ios) {
9593
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;
@@ -107,83 +105,119 @@ if (platform.isIOS) {
107105

108106
## Adding the MapView
109107

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.
108+
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:
111109

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

130137
## Properties
131138

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

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
141+
| Property | Description and Data Type
142+
:------------- | :---------------------------------
143+
`latitude` | Latitude, in degrees: `number`
144+
`longitude` | Longitude, in degrees: `number`
145+
`zoom` | Zoom level (described [here](https://developers.google.com/maps/documentation/javascript/tutorial#zoom-levels)): `number`
146+
`bearing` | Bearing, in degrees: `number`
147+
`tilt` | Tilt, in degrees: `number`
148+
`padding` | Top, bottom, left and right padding amounts, in Device Independent Pixels: `number[]` (array)
149+
`mapAnimationsEnabled` | Whether or not to animate camera changes: `Boolean`
143150

144151
## Events
145152

146153
The following events are available:
147154

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.
155+
| Event | Description
156+
:------------- | :---------------------------------
157+
`mapReady` | Fires when the MapView is ready for use
158+
`coordinateTapped` | Fires when a coordinate is tapped on the map
159+
`coordinateLongPress` | Fires when a coordinate is long-pressed on the map
160+
`markerSelect` | Fires when a marker is selected
161+
`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)*
155162
`markerBeginDragging` | Fires when a marker begins dragging
156-
`markerDrag` | Fires repeatedly while a marker is being dragged
157163
`markerEndDragging` | Fires when a marker ends dragging
158-
`markerInfoWindowTapped` | Fired on tapping Marker Info Window
159-
`cameraChanged` | Fired after the camera has changed
160-
`cameraMove` | Fired while the camera is moving
164+
`markerDrag` | Fires repeatedly while a marker is being dragged
165+
`markerInfoWindowTapped` | Fires when a marker's info window is tapped
166+
`cameraChanged` | Fires after the camera has changed
167+
`cameraMove` | Fires repeatedly while the camera is moving
168+
169+
## Native Map Object
170+
171+
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)
172+
173+
## UI Settings
174+
175+
You can adjust the map's UI settings after the `mapReady` event has fired by configuring the following properties on `mapView.settings`:
176+
177+
| Property | Description and Data Type
178+
:--------------- |:---------------------------------
179+
`compassEnabled` | Whether the compass is enabled or not: `Boolean`
180+
`indoorLevelPickerEnabled` | Whether the indoor level picker is enabled or not: `Boolean`
181+
`mapToolbarEnabled` | ** **Android only** ** Whether the map toolbar is enabled or not: `Boolean`
182+
`myLocationButtonEnabled` | Whether the 'My Location' button is enabled or not: `Boolean`
183+
`rotateGesturesEnabled` | Whether the compass is enabled or not: `Boolean`
184+
`scrollGesturesEnabled` | Whether map scroll gestures are enabled or not: `Boolean`
185+
`tiltGesturesEnabled` | Whether map tilt gestures are enabled or not: `Boolean`
186+
`zoomGesturesEnabled` | Whether map zoom gestures are enabled or not: `Boolean`
187+
`zoomControlsEnabled` | ** **Android only** ** Whether map zoom controls are enabled or not: `Boolean`
161188

189+
## Styling
190+
191+
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/)).
192+
193+
### Angular
194+
195+
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 }`.
162196

163-
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) )
197+
## Basic Example
164198

165199
```
166200
// /app/main-page.js
167201
168202
var mapsModule = require("nativescript-google-maps-sdk");
169203
170204
function onMapReady(args) {
171-
var mapView = args.object;
172-
173-
console.log("Setting a marker...");
174-
var marker = new mapsModule.Marker();
175-
marker.position = mapsModule.Position.positionFromLatLng(-33.86, 151.20);
176-
marker.title = "Sydney";
177-
marker.snippet = "Australia";
178-
marker.userData = { index : 1};
179-
mapView.addMarker(marker);
205+
var mapView = args.object;
206+
207+
console.log("Setting a marker...");
208+
var marker = new mapsModule.Marker();
209+
marker.position = mapsModule.Position.positionFromLatLng(-33.86, 151.20);
210+
marker.title = "Sydney";
211+
marker.snippet = "Australia";
212+
marker.userData = { index : 1};
213+
mapView.addMarker(marker);
180214
181-
// Disabling zoom gestures
182-
mapView.settings.zoomGesturesEnabled = false;
215+
// Disabling zoom gestures
216+
mapView.settings.zoomGesturesEnabled = false;
183217
}
184218
185219
function onMarkerSelect(args) {
186-
console.log("Clicked on " +args.marker.title);
220+
console.log("Clicked on " +args.marker.title);
187221
}
188222
189223
function onCameraChanged(args) {
@@ -200,40 +234,16 @@ exports.onCameraChanged = onCameraChanged;
200234
exports.onCameraMove = onCameraMove;
201235
```
202236

203-
## UI Settings
204-
205-
You can adjust the Map UI settings after mapReady by changing the below properties on `mapView.settings`
206-
207-
Property | Description
208-
-------------- |:---------------------------------
209-
`compassEnabled` | boolean - Whether the compass is enabled/disabled
210-
`indoorLevelPickerEnabled` | boolean - Whether the indoor level picker is enabled/disabled
211-
`mapToolbarEnabled` | boolean - Whether the indoor level picker is enabled/disabled ** ****Android only**** **
212-
`myLocationButtonEnabled` | boolean - Whether the my-location button is enabled/disabled
213-
`rotateGesturesEnabled` | boolean - Whether the compass is enabled/disabled
214-
`scrollGesturesEnabled` | boolean - Whether scroll gestures are enabled/disabled
215-
`tiltGesturesEnabled` | boolean - Whether tilt gestures are enabled/disabled
216-
`zoomControlsEnabled` | boolean - Whether the zoom controls are enabled/disabled ** ****Android only**** **
217-
`zoomGesturesEnabled` | boolean - Whether zoom gestures are enabled/disabled
218-
219-
220-
## Styling
221-
Use `gMap.setStyle(style);` to change the map styling.
222-
223-
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 }`.
224-
225-
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/).
226-
227237
## Custom Info Windows (Beta)
228238

229-
To customize the marker info windows, define a template in your view like so:
239+
To use custom marker info windows, define a template in your view like so:
230240

231241
```
232-
<!-- /app/main-page.xml -->
233-
<Page
234-
xmlns="http://www.nativescript.org/tns.xsd"
235-
xmlns:maps="nativescript-google-maps-sdk"
236-
>
242+
<!-- /app/main-page.xml -->
243+
<Page
244+
xmlns="http://www.nativescript.org/tns.xsd"
245+
xmlns:maps="nativescript-google-maps-sdk"
246+
>
237247
<GridLayout>
238248
<maps:mapView mapReady="onMapReady">
239249
<!-- Default Info Window Template -->
@@ -259,20 +269,20 @@ To customize the marker info windows, define a template in your view like so:
259269
</Page>
260270
```
261271

262-
If a marker has the `infoWindowTemplate` property set like so:
272+
...and set the `infoWindowTemplate` property like so:
263273

264274
```
265275
var marker = new mapsModule.Marker();
266276
marker.infoWindowTemplate = 'testWindow';
267277
```
268278

269-
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.
279+
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.
270280

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

273-
## Using with Angular
283+
## Usage with Angular
274284

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

277287
```
278288
// /app/map-example.component.ts
@@ -303,14 +313,16 @@ export class MapExampleComponent {
303313
```
304314
# Angular 8 Support
305315

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

308-
For now use this instead: `@ViewChild("MapView", {static: false}) mapView: ElementRef;`
318+
```
319+
@ViewChild("MapView", {static: false}) mapView: ElementRef;
320+
```
309321

310322

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

313-
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)
325+
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).
314326

315327
# Get Help
316328

0 commit comments

Comments
 (0)