dynamicmap.js

This file contains the DynamicMap model, which can be used to create dynamic, chainable map objects. Each instance of a DynamicMap object correlates with a different Google Map instance.

Don't access directly

It is extremely rare to need to create a DynamicMap model directly. You will almost always use the googleMaps singleton object to create and retrieve map objects.

For a more comprehensive explanation of how to use the internal API, check out the docs regarding the Universal Methods and JavaScript Methods.

# The map variable

For each example on this page, a map variable will be an instance of a specific DynamicMap object. Each example assumes that the map object has already been initialized, as demonstrated on the googlemaps.js page.

Get a Map

A map can be created using googleMaps.map, or retrieved using googleMaps.getMap.

# Map Methods

# markers(locations, options = [])

Add markers to an existing map. Does not overwrite any existing markers.

map.markers([
    {'lat': 40.730610, 'lng': -73.935242},  // New York
    {'lat': 34.052235, 'lng': -118.243683}, // Los Angeles
    {'lat': 41.881832, 'lng': -87.623177}   // Chicago
]);

Arguments

  • locations (coords|array) - See a description of acceptable locations...
  • options (array) - Optional parameters to configure the markers. (see below)
Option Type Default Description
id string "marker-{random}" Reference point for each marker.
icon object or string null An icon as defined by google.maps.MarkerOptions.
markerOptions object null Accepts any google.maps.MarkerOptions properties.
infoWindowOptions object null Accepts any google.maps.InfoWindowOptions properties.
markerLink string null URL to go to when marker is clicked.
markerClick function null JS callback function triggered when marker is clicked.

Returns

  • self - A chainable self-reference to this DynamicMap object.

# kml(url, options = [])

Append a KML layer to an existing map object.

Arguments

  • url (string) - Publicly accessible URL of the KML file.
  • options (array) - Optional parameters to configure the KML layer. (see below)
Option Type Default Description
id string "kml-{random}" Reference point for each KML layer.
kmlLayerOptions object null Accepts any google.maps.KmlLayerOptions properties.
map.kml('https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml');

Creating a KML file

KML files can be created using Google My Maps or a similar service.

Must be publicly accessible

In order for a KML file to work, it must exist at a publicly available URL.

Returns

  • self - A chainable self-reference to this DynamicMap object.

# styles(styleSet)

Style a map based on a given collection of styles.

Generating Styles

For more information on how to generate a set of styles, read Styling a Map.

Arguments

  • styleSet (array) - A set of styles to be applied to the map.
map.styles([
    {
        "featureType": "landscape",
        "stylers": [
            {"color": "#f9ddc5"},
            {"lightness": -7}
        ]
    },
    {
        "featureType": "road",
        "stylers": [
            {"color": "#813033"},
            {"lightness": 43}
        ]
    }
]);

Returns

  • self - A chainable self-reference to this DynamicMap object.

# zoom(level)

Change the map's zoom level.

Arguments

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

Zoom Level Reference

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

Returns

  • self - A chainable self-reference to this DynamicMap object.

# center(coords)

Re-center the map.

Arguments

  • coords (coords) A simple key-value set of coordinates.
map.center({
   'lat': 32.3113966,
   'lng': -64.7527469
});

Returns

  • self - A chainable self-reference to this DynamicMap object.

# fit()

Zoom and center map to fit all markers within the viewing area. Internally uses fitBounds.

map.fit();

Returns

  • self - A chainable self-reference to this DynamicMap object.

# 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.

map.refresh();

Returns

  • self - A chainable self-reference to this DynamicMap object.

# Marker Methods

Automatically generated marker IDs

If the marker has been created from an Element, it will have a marker ID matching this formula:

    [ELEMENT ID]-[FIELD HANDLE]

Let's say you have an Address field with the handle of address attached to your Entries. When you use those entries to create a map, the markers will generate IDs similar to this:

    21-address
    33-address
    42-address
    etc...

Conversely, if the markers have been created manually via JavaScript, it will use the marker ID specified in the options, or even stowed alongside the coordinates.

If no marker ID is specified, new markers will use a randomly generated ID.


# panToMarker(markerId)

Re-center map on the specified marker.

map.panToMarker('33-address');

Arguments

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

Returns

  • self - A chainable self-reference to this DynamicMap object.

# openInfoWindow(markerId)

Open the info window of a specific marker.

map.openInfoWindow('33-address');

Arguments

  • markerId (string) - The ID of the marker with the info window that you want to open.

Returns

  • self - A chainable self-reference to this DynamicMap object.

# setMarkerIcon(markerId, icon)

Set the icon of an existing marker. Internally uses setIcon.

map.setMarkerIcon('33-address', 'http://maps.google.com/mapfiles/ms/micons/green.png');

Arguments

  • markerId (string) - The ID of the marker that you want to set the icon for.
  • icon (string|icon) - The icon to set on the specified marker.

Returns

  • self - A chainable self-reference to this DynamicMap object.

# hideMarker(markerId)

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

map.hideMarker('33-address');

Arguments

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

Returns

  • self - A chainable self-reference to this DynamicMap object.

# showMarker(markerId)

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

map.showMarker('33-address');

Arguments

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

Returns

  • self - A chainable self-reference to this DynamicMap object.

# hideKml(kmlId)

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

map.hideKml('my-kml');

Arguments

  • kmlId (string) - The ID of the KML layer that you want to hide.

Returns

  • self - A chainable self-reference to this DynamicMap object.

# showKml(kmlId)

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

map.showKml('my-kml');

Arguments

  • kmlId (string) - The ID of the KML layer that you want to show.

Returns

  • self - A chainable self-reference to this DynamicMap object.

# Non-Chainable Methods

Breaking the Chain

The following methods are the only ones which do not return a chainable map object.

# getMarker(markerId)

Get the Google Maps Marker object of a specified marker.

var marker = map.getMarker('33-address');

Arguments

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

Returns


# getInfoWindow(markerId)

Get the Google Maps Info Window object of a specified info window.

var infoWindow = map.getInfoWindow('33-address');

Arguments

  • markerId (string) - The ID of the marker with the info window that you want to access.

Returns


# getKml(kmlId)

Get the Google Maps KML Layer object of a specified KML layer.

var kml = map.getKml('my-kml');

Arguments

  • kmlId (string) - The ID of the KML layer that you want to access.

Returns


# getMarkerClusterer()

If clustering is enabled, get the Google Maps MarkerClusterer object.

var clusterer = map.getMarkerClusterer();

Returns


# tag(options = {})

Creates a new <div> element, detached from the DOM. If a parentId is specified, the element will automatically be injected into the specified parent container.

map.tag({'parentId': 'target-parent-id'});

Arguments

  • options (array) - Configuration options for the rendered dynamic map.
Option Type Default Description
parentId string null The ID of the target parent container for the newly created element.

Returns

  • A new DOM element. Will always return the newly created element, regardless of whether it was automatically injected into a parent container.