Google Maps plugin for Craft CMS

Universal Methods

The following methods apply equally, whether you are working in JavaScript, Twig, or PHP. These methods have nearly identical parameters and behaviors across all three languages.

The Magic of Chaining

Each of these methods can be chained together in any order you'd like. Chaining can be a powerful technique, allowing you to build complex maps with ease.

There are also a few language-specific methods to be aware of. In addition to the Universal Methods below, check out the extended documentation for JavaScript Methods and Twig & PHP Methods.

# markers(locations, options)

map.markers(locations, options);

Places additional markers onto the map.

Arguments

  • locations (locations) - Will be used to create additional markers for the map.
  • options (array|null) - The options parameter allows you to configure the markers in greater detail. These options will only apply to the markers created in this method call.

Available Options

Most, but not all, of these options are available across JavaScript, Twig, and PHP. Please note the few options which are not universally available.

Option Available Description
id JavaScript, Twig/PHP Reference point for each marker.
icon JavaScript, Twig/PHP An icon as defined by google.maps.MarkerOptions (opens new window).
markerOptions JavaScript, Twig/PHP Accepts any google.maps.MarkerOptions (opens new window) properties.
infoWindowOptions JavaScript, Twig/PHP Accepts any google.maps.InfoWindowOptions (opens new window) properties.
infoWindowTemplate Twig/PHP Template path to use for creating info windows.
infoWindowData Twig/PHP Additional data for passing into an info window.
markerLink JS/Twig/PHP URL to go to when marker is clicked.
markerClick JS/Twig/PHP JS callback function triggered when marker is clicked.
field Twig/PHP Address field(s) to be included on the map. (includes all by default)

Additional Options Details

For more info, please consult either the JavaScript object or the Dynamic Map model.

# circles(locations, options)

map.circles(locations, options);

Places one or more circles onto the map.

Arguments

  • locations (locations) - Will be used to add circles to the map.
  • options (array|null) - The options parameter allows you to configure circles in greater detail.
Option Available Description
id JavaScript, Twig/PHP Reference point for each circle.
circleOptions JavaScript, Twig/PHP Accepts any google.maps.CircleOptions (opens new window) properties.

How to Draw Circles

For a more elaborate explanation, see the guide for Drawing Circles...

# kml(url, options)

map.kml(url, options);

Applies a KML layer to the map.

Arguments

  • url (string) - The URL of a KML or KMZ file. Relative and local URLs work fine. A file on another domain must allow cross-origin requests.
  • options (array|null) - The options parameter allows you to configure this KML layer in greater detail.
Option Available Description
id JavaScript, Twig/PHP Reference point for each KML layer.
preserveViewport JavaScript, Twig/PHP If true, the map will not zoom to fit the layer once it loads.
suppressInfoWindows JavaScript, Twig/PHP If true, clicking a shape will not open an info window.
clickable JavaScript, Twig/PHP If false, the layer will ignore clicks entirely.
zIndex JavaScript, Twig/PHP Stacking order of the layer, relative to other layers.
style JavaScript, Twig/PHP Any google.maps.Data.StyleOptions (opens new window) properties. Overrides the styles from the KML file.
kmlLayerOptions JavaScript, Twig/PHP Any of the options above, nested. If an option is set both ways, the nested value wins.

ID required to dynamically adjust KML layers

In order to further manipulate a KML layer, you must provide an id option value.

For more information, see the KML Layers guide.

# geoJson(source, options)

map.geoJson(source, options);

Applies a GeoJSON layer to the map.

Arguments

  • source (string|array) - The URL of a GeoJSON file, a JSON string, or the GeoJSON data itself.
  • options (array|null) - The options parameter allows you to configure this GeoJSON layer in greater detail.
Option Available Description
id JavaScript, Twig/PHP Reference point for each GeoJSON layer.
preserveViewport JavaScript, Twig/PHP If true, the map will not zoom to fit the layer once it loads.
suppressInfoWindows JavaScript, Twig/PHP If true, clicking a shape will not open an info window.
clickable JavaScript, Twig/PHP If false, the layer will ignore clicks entirely.
zIndex JavaScript, Twig/PHP Stacking order of the layer, relative to other layers.
style JavaScript, Twig/PHP Any google.maps.Data.StyleOptions (opens new window) properties. Overrides the styles from the GeoJSON data.

For more information, see the GeoJSON Layers guide.

# gpx(url, options)

map.gpx(url, options);

Applies a GPX layer (tracks, routes, and waypoints) to the map.

Arguments

  • url (string) - The URL of a GPX file. Relative and local URLs work fine. A file on another domain must allow cross-origin requests.
  • options (array|null) - The options parameter allows you to configure this GPX layer in greater detail.
Option Available Description
id JavaScript, Twig/PHP Reference point for each GPX layer.
preserveViewport JavaScript, Twig/PHP If true, the map will not zoom to fit the layer once it loads.
suppressInfoWindows JavaScript, Twig/PHP If true, clicking a track or waypoint will not open an info window.
clickable JavaScript, Twig/PHP If false, the layer will ignore clicks entirely.
zIndex JavaScript, Twig/PHP Stacking order of the layer, relative to other layers.
style JavaScript, Twig/PHP Any google.maps.Data.StyleOptions (opens new window) properties.

For more information, see the GPX Tracks guide.

# groundOverlay(url, bounds, options)

map.groundOverlay(url, bounds, options);

Places an image onto the map, stretched to fit the specified bounds.

Arguments

  • url (string) - The URL of the image.
  • bounds (array) - The edges of the image, as north, south, east, and west values.
  • options (array|null) - The options parameter allows you to configure this ground overlay in greater detail.
Option Available Description
id JavaScript, Twig/PHP Reference point for each ground overlay.
opacity JavaScript, Twig/PHP Opacity of the image, from 0 (invisible) to 1 (solid).
clickable JavaScript, Twig/PHP If false, the image will ignore clicks.

For more information, see the Ground Overlays guide.

# dataset(datasetId, options)

map.dataset(datasetId, options);

Shows a dataset which has been uploaded to Google Cloud. Requires a vector Map ID.

Arguments

  • datasetId (string) - The ID of the dataset in Google Cloud.
  • options (array|null) - The options parameter allows you to configure this dataset in greater detail.
Option Available Description
id JavaScript, Twig/PHP Reference point for the dataset. Defaults to the dataset ID.
style JavaScript, Twig/PHP Any google.maps.FeatureStyleOptions (opens new window) properties.
suppressInfoWindows JavaScript, Twig/PHP If true, clicking a shape will not open an info window.

For more information, see the Datasets & Boundaries guide.

# boundaries(featureType, placeIds, options)

map.boundaries(featureType, placeIds, options);

Shades Google's own boundaries of countries, states, cities, and more. Requires a vector Map ID.

Arguments

  • featureType (string) - The type of boundary. One of COUNTRY, ADMINISTRATIVE_AREA_LEVEL_1, ADMINISTRATIVE_AREA_LEVEL_2, LOCALITY, POSTAL_CODE, or SCHOOL_DISTRICT.
  • placeIds (string|array) - A Place ID, or array of Place IDs, of the areas to shade.
  • options (array|null) - The options parameter allows you to configure these boundaries in greater detail.
Option Available Description
id JavaScript, Twig/PHP Reference point for the boundaries. Defaults to the feature type.
style JavaScript, Twig/PHP Any google.maps.FeatureStyleOptions (opens new window) properties.

For more information, see the Datasets & Boundaries guide.

# styles(styleSet)

map.styles(styleSet);

Arguments

  • styleSet (array) - A collection of styles, most likely generated elsewhere.

For more information, see the Styling a Map guide.

# zoom(level)

map.zoom(level);

Change the map's zoom level.

Arguments

  • level (int) - The new zoom level. Must be an integer between 1 - 22.

Zoom Level Reference

  • 1 is extremely zoomed out, a view of the entire planet.
  • 22 is extremely zoomed in, as close to the ground as possible.

# center(coords)

map.center(coords);

Re-center the map.

Arguments

  • coords (coords) - New center point of map.

# fit()

map.fit();

Zoom map to automatically fit all markers and layers within the viewing area. Internally uses fitBounds (opens new window).

Which layers are included?

KML, GeoJSON, and GPX layers and ground overlays are included, as long as they are visible and have finished loading. Datasets and boundaries are left out, since Google doesn't provide their bounds.

# refresh()

map.refresh();

Refresh an existing map. You may need to do this after the page has been resized, or if something has been moved or changed.

# Marker ID formula

The remaining methods all refer to a markerId value.

Formula

The default formula for a markerId is as follows:

    '[ELEMENT ID]-[FIELD HANDLE]' // eg: '101-myAddressField'

# panToMarker(markerId)

map.panToMarker(markerId);

Re-center map on the specified marker.

Arguments

  • markerId (string) - The ID of the marker that you want to pan to.

# setMarkerIcon(markerId, icon)

map.setMarkerIcon(markerId, icon);

Set the icon of an existing marker. Internally uses setIcon (opens new window).

Arguments

  • markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all markers.
  • icon (string|icon (opens new window)) - The icon to set on the specified marker.

# hideMarker(markerId)

map.hideMarker(markerId);

Hide a marker. The marker will not be destroyed, it will simply be detached from the map.

Arguments

  • markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all markers.

# showMarker(markerId)

map.showMarker(markerId);

Show a marker. The marker will be re-attached to the map.

Arguments

  • markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all markers.

# openInfoWindow(markerId)

map.openInfoWindow(markerId);

Open the info window of a specific marker.

Arguments

  • markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all info windows.

# closeInfoWindow(markerId)

map.closeInfoWindow(markerId);

Close the info window of a specific marker.

Arguments

  • markerId (string|array|'*') - A marker ID, array of marker IDs, or '*' for all info windows.

# hideCircle(circleId)

map.hideCircle(circleId);

Hide a circle. The circle will not be destroyed, it will simply be detached from the map.

Arguments

  • circleId (string|array|'*') - A circle ID, array of circle IDs, or '*' for all circles.

# showCircle(circleId)

map.showCircle(circleId);

Show a circle. The circle will be re-attached to the map.

Arguments

  • circleId (string|array|'*') - A circle ID, array of circle IDs, or '*' for all circles.

# hideKml(kmlId)

map.hideKml(kmlId);

Hide a KML layer. The KML layer will not be destroyed, it will simply be detached from the map.

Arguments

  • kmlId (string|array|'*') - A KML layer ID, array of KML layer IDs, or '*' for all KML layers.

# showKml(kmlId)

map.showKml(kmlId);

Show a KML layer. The KML layer will be re-attached to the map.

Arguments

  • kmlId (string|array|'*') - A KML layer ID, array of KML layer IDs, or '*' for all KML layers.

# hideGeoJson(geoJsonId)

map.hideGeoJson(geoJsonId);

Hide a GeoJSON layer. The GeoJSON layer will not be destroyed, it will simply be detached from the map.

Arguments

  • geoJsonId (string|array|'*') - A GeoJSON layer ID, array of GeoJSON layer IDs, or '*' for all GeoJSON layers.

# showGeoJson(geoJsonId)

map.showGeoJson(geoJsonId);

Show a GeoJSON layer. The GeoJSON layer will be re-attached to the map.

Arguments

  • geoJsonId (string|array|'*') - A GeoJSON layer ID, array of GeoJSON layer IDs, or '*' for all GeoJSON layers.

# hideGpx(gpxId)

map.hideGpx(gpxId);

Hide a GPX layer. The GPX layer will not be destroyed, it will simply be detached from the map.

Arguments

  • gpxId (string|array|'*') - A GPX layer ID, array of GPX layer IDs, or '*' for all GPX layers.

# showGpx(gpxId)

map.showGpx(gpxId);

Show a GPX layer. The GPX layer will be re-attached to the map.

Arguments

  • gpxId (string|array|'*') - A GPX layer ID, array of GPX layer IDs, or '*' for all GPX layers.

# hideGroundOverlay(overlayId)

map.hideGroundOverlay(overlayId);

Hide a ground overlay. The ground overlay will not be destroyed, it will simply be detached from the map.

Arguments

  • overlayId (string|array|'*') - A ground overlay ID, array of ground overlay IDs, or '*' for all ground overlays.

# showGroundOverlay(overlayId)

map.showGroundOverlay(overlayId);

Show a ground overlay. The ground overlay will be re-attached to the map.

Arguments

  • overlayId (string|array|'*') - A ground overlay ID, array of ground overlay IDs, or '*' for all ground overlays.

# hideDataset(datasetId)

map.hideDataset(datasetId);

Hide a dataset. The dataset will not be destroyed, it will simply be hidden from view.

Arguments

  • datasetId (string|array|'*') - A dataset ID, array of dataset IDs, or '*' for all datasets.

# showDataset(datasetId)

map.showDataset(datasetId);

Show a dataset. The dataset will be shown again.

Arguments

  • datasetId (string|array|'*') - A dataset ID, array of dataset IDs, or '*' for all datasets.

# hideBoundaries(boundariesId)

map.hideBoundaries(boundariesId);

Hide boundaries. The boundaries will not be destroyed, they will simply be hidden from view.

Arguments

  • boundariesId (string|array|'*') - A boundaries ID, array of boundaries IDs, or '*' for all boundaries.

# showBoundaries(boundariesId)

map.showBoundaries(boundariesId);

Show boundaries. The boundaries will be shown again.

Arguments

  • boundariesId (string|array|'*') - A boundaries ID, array of boundaries IDs, or '*' for all boundaries.

← Additional JavaScript Methods →