# Google Maps

## svyGMaps

This guide provides comprehensive documentation for using the **svyGMaps** web-component, which allows you to display a location using the Google Maps API within Servoy's NGClient.\
To see a live sample of the component you can go [here](https://samples-dev.samples.servoy-cloud.eu/solution/components?a=googleMaps).

Table of contents

* [Getting Started](#getting-started)
* [Example Usage](#example-usage)
* [svyGMaps Properties](#svygmaps-properties)
* [svyGMaps API](#svygmaps-api)
* [svyGMaps Events](#svygmaps-events)
* [Custom types](#custom-types)

## Getting Started

First import the component using one of the release [binaries](https://github.com/Servoy/svyGMaps/releases) or via Servoy's Web Package Manager.

If you would like to see the component in an example install the included solution, [googleMapsExample.servoy](https://github.com/Servoy/svyGMaps/releases).

Most importantly the component **requires** a Google Map API key to function properly. You can get one [here](https://developers.google.com/maps/documentation/javascript/get-api-key) for free. Make sure to enable the GeoCoding API in addition to the Javascript Map API options.

## Example Usage

First add the component to a form and setup the apiKey.\
Next you can add one or multiple markers to the component.\
This can be done by adding markers in the property panel or from code.\
You can add additional styling to the component using the styleClass property.\
For more information check out the example solution.

### svyGMaps Properties

svyGMaps properties can be found [here](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#properties).

### svyGMaps API

svyGMaps API methods can be found [here](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#api).\
The component offers the following API methods:

#### [createMarker](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#createmarker)

Creates a new, empty marker:

```javascript
var servoyMarker = elements.map.createMarker('svyMarker', 'Fred. Roeskestraat 97, 1076 EC Amsterdam', 'Servoy B.V.');
servoyMarker.iconMedia = 'media:///servoy_marker.png';
elements.map.addMarker(servoyMarker);
```

#### [addMarker](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#addmarker)

Adds the given marker at the optional index.

```javascript
var servoyMarker = elements.map.createMarker('svyMarker', 'Fred. Roeskestraat 97, 1076 EC Amsterdam', 'Servoy B.V.');
servoyMarker.iconMedia = 'media:///servoy_marker.png';
elements.map.addMarker(servoyMarker);
```

#### [addMarkers](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#addmarkers)

Adds the given markers at the optional index.

```javascript
var markers = [];
markers.push(elements.map.createMarker('marker-1', 'Fred. Roeskestraat 97, 1076 EC Amsterdam', 'Servoy'));
markers.push(elements.map.createMarker('marker-2', '1600 Pennsylvania Avenue NW, Washington, DC 20500', 'White House'));
elements.map.addMarkers(markers);
```

#### [getMarker](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#getmarker)

Returns the marker at the given index

```javascript
var marker = elements.map.getMarker(index);
```

#### [getMarkerById](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#getmarkerbyid)

Returns the marker with the given Id

```javascript
var marker = elements.map.getMarkerById(markerId);
```

#### [getMarkers](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#getmarkers)

Returns all markers

#### [removeMarker](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#removemarker)

Api to remove markers at given index.

```javascript
elements.map.removeMarker(5);
```

#### [removeAllMarkers](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#removeallmarkers)

Api to remove all markers

```javascript
elements.map.removeAllMarkers();
```

#### [refresh](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#refresh)

Api to force refresh google maps

```javascript
elements.map.refresh();
```

#### [centerAtAddress](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#centerataddress)

Api to center the map at given address

```javascript
elements.map.centerAtAddress(shipaddress + ' ' + shipcity + ' ' + shipcountry);
```

#### [centerAtLatLng](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#centeratlatlng)

Api to center the map at given lat long location

```javascript
elements.map.centerAtLatLng(33,-111);
```

#### [getBounds](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#getbounds)

Returns the lat/lng bounds of the current viewport as a `latLngBounds` object. If more than one copy of the world is visible, the bounds range in longitude from -180 to 180 degrees inclusive. If the map is not yet initialized (i.e. the mapType is still null), or center and zoom have not been set then the result is `null` or `undefined`.

#### [getCenter](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#getcenter)

Returns the position displayed at the center of the map as a `latLng` object.

#### [fitBounds](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#fitbounds)

Sets the viewport to contain the given bounds (as `latLngBounds` object).

#### [setOptions](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#setoptions)

Sets Google Maps options. See here: <https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions> the list of available options.

### svyGMaps Events

svyGMaps events can be found [here](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#events).

#### [onMapEvent](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#onmapevent)

Callback method for any events assigned in the mapEvents property.

To listen for map events, use the mapEvents property to assign the events you want to listen for (e.g. "click"). The callback method will be fired whenever one of the events in the mapEvents list is detected and receives the event and an optional latLng object (Mouse events like "click" only).

#### [onMarkerEvent](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#onmarkerevent)

Callback method for any events assigned in the markerEvents property.

To listen for marker events, use the markerEvents property to assign the events you want to listen for (e.g. "click"). The callback method will be fired whenever one of the events in the markerEvents list is detected and receives the event, the marker index and an optional latLng object (Mouse events like "click" only).

#### [onMarkerGeocoded](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#onmarkergeocoded)

Callback method that fires whenever an address from a marker has successfully been geocoded.

#### [onRouteChanged](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#onroutechanged)

Function call when the route is changed.

### Custom types

svyGMaps custom types can be found [here](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#types).

#### [marker](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#marker)

When using in code you can define this type by using:

```javascript
    /** @type {CustomType<googlemaps-svy-G-Maps.marker>} */
    var marker = {}
```

or by calling

```javascript
var marker = elements.map.createMarker(...)
```

#### [routeSettings](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#routesettings)

Settings for the route calculation, set on the `directionsSettings` property.

#### [routeResult](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#routeresult)

A route result object provided to the `onRouteChanged` handler holding all legs of the route and the total number of meters and the total number of seconds of the route calculated.

#### [leg](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#leg)

A single leg of a route result

#### [latLng](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#latlng)

A latLng is a point in geographical coordinates: latitude and longitude.

#### [latLngBounds](https://docs.servoy.com/reference/servoyextensions/ui-components/visualization/google-maps#latlngbounds)

A latLngBounds instance represents a rectangle in geographical coordinates, including one that crosses the 180 degrees longitudinal meridian.