Google Maps

Provides an easy markup-driven interface to the Google Maps API


About the Plugin

We created this plugin to simplify embedding Google Maps through markup.

The required Google Maps API javascript is loaded automatically and Maps instances are initialized on page load.

Features
  • Geocoded or Lat/long map center location
  • Multiple map markers
  • Geocoded or or Lat/long map marker location
  • Same icon for all markers or custom marker icon per marker
  • HTML info window per marker
  • Configurable zoom controls position
  • Set zoom level
  • Custom map styles

Initializing

The demo pages already include the following code. These steps are only necessary if you are building a page from scratch. Remove these references if you are not using this plugin to improve page load times.

  1. Declare the following import statement in js/mrare/index.js. This ensures that the initializer code is included in the theme.js bundle.

    import mrMaps from './maps';
  2. Ensure the following line appears in the export object:

    export {
    mrMaps,
    };

Basic Usage

To set up a map, create a <div> with data attribute data-maps-api-key. Insert your Google maps API key as the value.

The main <div> requires a min-height to be set, so add a height utility class like so: class="min-vh-50".

For easy map positioning, provide an address for the center of the map in the data-address attribute on the same <div>.

Add an empty <div> with class map-marker to add a marker to the map. Add the data-address attribute and provide an address as the value.

This will create a Map, center it at the provided address and add a marker at the specified address. This is the most basic functionality and will use the default marker image at assets/img/map-marker.png.

<div class="min-vh-50" data-maps-api-key="INSERT_YOUR_GOOGLE_MAPS_API_KEY_HERE" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn New York" data-map-zoom="14">
  <div class="map-marker" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn, New York"></div>
</div>

Map elements that you include in your HTML are 'digested' and transformed into Google Map instances upon page load.

Centering the Map

The center of the map is set by either data-address or data-latlong attribute on the main map <div>.

Only choose one of the following options for each map.

Using an address

Add data-address to the map's containing <div> and specify your desired center address in a format that is readable by Google Maps. Provide as much detail as possible for the Geocoder to pinpoint the address. Try the address in the Google Maps app on your PC or mobile device. If the Google Maps app finds the address accurately, you can safely use the same address string in your data-address attribute.

Using data-address will incur API fees as each individual call to the Google Maps Geocoder is itemised on your bill.

<div class="min-vh-50" data-maps-api-key="INSERT_YOUR_GOOGLE_MAPS_API_KEY_HERE" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn New York"></div>
Using latitude / longitude

Add data-latlong to the map's containing <div> and specify the latitude and longitude of the desired location in comma-separated format.

You can find the latitude / longitude of an address by using a service such as LatLong.net.

<div class="min-vh-50" data-maps-api-key="INSERT_YOUR_GOOGLE_MAPS_API_KEY_HERE" data-latlong="40.667412,-73.947960"></div>

Setting Zoom

The default zoom level for the map is 17. To set the map's zoom level, add data-zoom to the map's containing <div> with a number as the value.

The number you provide must be between 1 and 20.

As stated in the Google Maps JS API Documentation:

Zoom Level What you will see
1 World
5 Landmass/continent
10 City
15 Streets
20 Buildings

This example shows setting the zoom level to 20:

<div class="min-vh-50"
     data-map-zoom="20"
     data-zoom-controls="BOTTOM_RIGHT" 
     data-maps-api-key="INSERT_YOUR_GOOGLE_MAPS_API_KEY_HERE" 
     data-address="389 Greenpoint Ave, Crown Heights, Brooklyn New York">
</div>

Zoom Controls

By default, the map's zoom controls are hidden. To show the zoom controls on the map, add data-zoom-controls attribute to the containing map <div> and provide a position string as the value.

Supported strings:

String Positioning
BOTTOM_CENTER Elements are positioned in the center of the bottom row.
BOTTOM_LEFT Elements are positioned in the bottom left and flow towards the middle. Elements are positioned to the right of the Google logo.
BOTTOM_RIGHT Elements are positioned in the bottom right and flow towards the middle. Elements are positioned to the left of the copyrights.
LEFT_BOTTOM Elements are positioned on the left, above bottom-left elements, and flow upwards.
LEFT_CENTER Elements are positioned in the center of the left side.
LEFT_TOP Elements are positioned on the left, below top-left elements, and flow downwards.
RIGHT_BOTTOM Elements are positioned on the right, above bottom-right elements, and flow upwards.
RIGHT_CENTER Elements are positioned in the center of the right side.
RIGHT_TOP Elements are positioned on the right, below top-right elements, and flow downwards.
TOP_CENTER Elements are positioned in the center of the top row.
TOP_LEFT Elements are positioned in the top left and flow towards the middle.
TOP_RIGHT Elements are positioned in the top right and flow towards the middle.

The following diagram places the string initials visually:

  +----------------+ 
  + TL    TC    TR + 
  + LT          RT + 
  +                + 
  + LC          RC + 
  +                + 
  + LB          RB + 
  + BL    BC    BR + 
  +----------------+ 

For example, to make the zoom controls appear in the bottom, right corner of the map, use the following:

<div class="min-vh-50" data-zoom-controls="BOTTOM_RIGHT" data-maps-api-key="INSERT_YOUR_GOOGLE_MAPS_API_KEY_HERE" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn New York" data-map-zoom="14"></div>

More detail on other positioning strings can be found at the Google Maps JS API Documentation.

Markers

You may add many markers to your map. Each marker is represented by a div.map-marker element as a direct child of the map.

  • Markers can be positioned using either data-address or data-latlong.
  • Each marker may use its own image specified by the data-marker-image attribute.
  • Markers contain Info Windows (see Info Windows section below).
Multiple Markers

In this example, each marker is positioned using an address, and the marker image will default to the asset located at assets/img/map-marker.png.

<div data-maps-api-key="INSERT_YOUR_GOOGLE_MAPS_API_KEY_HERE" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn New York" data-map-zoom="14">
  <div class="map-marker" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn, New York"></div>
  <div class="map-marker" data-address="2213 Montgomery Street, San Francisco, California"></div>
  <div class="map-marker" data-address="4928 Lincoln Boulevard, Santa Monica, Los Angeles, California"></div>
</div>
Positioning Markers
  • Using an address

    Add data-address to the marker's <div> and specify your desired marker address in a format that is readable by Google Maps. Provide as much detail as possible for the Geocoder to pinpoint the address. Try the address in the Google Maps app on your PC or mobile device. If the Google Maps app finds the address accurately, you can safely use the same address string in your data-address attribute.

    <div class="map-marker" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn, New York"></div>
  • Using latitude / longitude

    Add data-latlong to the marker's <div> and specify the latitude and longitude of the desired location in comma-separated format.

    You can find the latitude / longitude of an address by using a service such as LatLong.net.

    <div class="map-marker" data-latlong="40.667412,-73.947960"></div>

    Each marker that uses data-address will incur API fees as each individual call to the Google Maps Geocoder is itemised on your bill. Markers using data-latlong are not charged.

Setting Marker Title

The marker title is a small popover that appears when the user hovers on the marker. Set the marker title text by adding data-marker-title attribute and setting your text as the value:

  <div class="map-marker" data-title="Brooklyn Branch" data-latlong="40.667412,-73.947960"></div>
Setting Marker Image
  • Setting data-marker-image on the map's containing <div> will set the default for all markers in the map to the same image.

  • Setting data-marker-image on the div.map-marker overrides the default set on the map <div> for that single map marker.

If data-marker-image is not specified on either the marker div.map-marker or the main map <div>, the default assets/img/map-marker.png will be used for all markers on the map.

Info Windows

An info window displays content (usually text or images) in a popup window above the map, at a given location. The info window has a content area and a tapered stem.

The tip of the stem is attached to a specified location on the map. The info window will always point to a map marker.

You may use any markup inside the info window to display information about the marker's location.

Bootstrap markup is also allowed in Info Windows.

This example includes an info window on the map marker.

<div data-maps-api-key="INSERT_YOUR_GOOGLE_MAPS_API_KEY_HERE" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn New York" data-map-zoom="14">
  <div class="map-marker" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn, New York">
    <div class="info-window" data-max-width="400">
      <div class="container">
        <div class="row">
          <div class="col-12">
            <h5>Info windows are great!</h5>
          </div>
          <div class="col-4">
            <img alt="Logo" class="w-100" src="assets/img/logo.svg">
          </div>
          <div class="col-8 pb-2">
            <p>
              We've made info windows easy, so you can use any HTML in this info window on your map.
            </p>
            <h6 class="mb-0">Address</h6>
            <address>
              389 Greenpoint Ave Crown Heights, Brooklyn New York
            </address>
            <a target="_blank" href="#purchase">... More Info</a>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>
Options

The following options may be applied to a div.info-window as data attributes:

Data attribute Default Usage
data-max-width 250 Sets the width of the info window (in pixels) within the map container.

Map Style

The map may be styled using a JSON array of objects recognised by Google Maps. You can create styles and download pre-made styles using an online service such as Snazzy Maps

To set the style of your map there are two options:

  • Embed the style JSON in your HTML (styles on a per-map basis).
  • Provide the style in Javascript by editing js/mrare/maps-style.js (provides a default style for all maps).

Both methods accept the same JSON formatted array structure. See below for detailed instructions on each method.

Map Style in HTML

The script will look for a <div> with class map-style nested as a direct child of the main map <div>.

The text content of the div is expected to be properly formatted JSON and is parsed on page load.

This example uses the Light Dream preset found on Snazzy Maps. The text was copied directly from the code box on Snazzy Maps and pasted as the only text inside the div.map-style. If the text is valid JSON, the style will work as expected.

<div data-maps-api-key="INSERT_YOUR_GOOGLE_MAPS_API_KEY_HERE" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn New York" data-map-zoom="14">
  <div class="map-marker" data-address="389 Greenpoint Ave, Crown Heights, Brooklyn, New York">
  </div>
  <div class="map-style">
    [
        {
            "featureType": "landscape",
            "stylers": [
                {
                    "hue": "#FFBB00"
                },
                {
                    "saturation": 43.400000000000006
                },
                {
                    "lightness": 37.599999999999994
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "road.highway",
            "stylers": [
                {
                    "hue": "#FFC200"
                },
                {
                    "saturation": -61.8
                },
                {
                    "lightness": 45.599999999999994
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "road.arterial",
            "stylers": [
                {
                    "hue": "#FF0300"
                },
                {
                    "saturation": -100
                },
                {
                    "lightness": 51.19999999999999
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "road.local",
            "stylers": [
                {
                    "hue": "#FF0300"
                },
                {
                    "saturation": -100
                },
                {
                    "lightness": 52
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "water",
            "stylers": [
                {
                    "hue": "#0078FF"
                },
                {
                    "saturation": -13.200000000000003
                },
                {
                    "lightness": 2.4000000000000057
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "poi",
            "stylers": [
                {
                    "hue": "#00FF6A"
                },
                {
                    "saturation": -1.0989010989011234
                },
                {
                    "lightness": 11.200000000000017
                },
                {
                    "gamma": 1
                }
            ]
        }
    ]
  </div>
</div>

Map Style in Javascript

If you prefer to keep the style out of your HTML and leave it in javascript, copy the JSON formatted array to the js/mrare/maps-style.js file.

This example uses the Light Dream preset found on Snazzy Maps.

The javascript in maps-style.js must declare a variable mrMapStyle, assign it an array and export it.

This example shows a properly formatted style array in maps-style.js. Note that the array can be pasted straight in from Snazzy Maps, even though the Snazzy maps array is JSON.

const mrMapStyle = [
        {
            "featureType": "landscape",
            "stylers": [
                {
                    "hue": "#FFBB00"
                },
                {
                    "saturation": 43.400000000000006
                },
                {
                    "lightness": 37.599999999999994
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "road.highway",
            "stylers": [
                {
                    "hue": "#FFC200"
                },
                {
                    "saturation": -61.8
                },
                {
                    "lightness": 45.599999999999994
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "road.arterial",
            "stylers": [
                {
                    "hue": "#FF0300"
                },
                {
                    "saturation": -100
                },
                {
                    "lightness": 51.19999999999999
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "road.local",
            "stylers": [
                {
                    "hue": "#FF0300"
                },
                {
                    "saturation": -100
                },
                {
                    "lightness": 52
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "water",
            "stylers": [
                {
                    "hue": "#0078FF"
                },
                {
                    "saturation": -13.200000000000003
                },
                {
                    "lightness": 2.4000000000000057
                },
                {
                    "gamma": 1
                }
            ]
        },
        {
            "featureType": "poi",
            "stylers": [
                {
                    "hue": "#00FF6A"
                },
                {
                    "saturation": -1.0989010989011234
                },
                {
                    "lightness": 11.200000000000017
                },
                {
                    "gamma": 1
                }
            ]
        }
    ];

export default mrMapStyle;

Events

When the map has been initialized, it can then be manipulated through the Google Maps API.

The maps script emits an event loaded.mr.maps.

You can access map instances by listening for the loaded.mr.maps event which will fire when the map has been centred at the specified location. The Google Map instance is passed in to the event as map.

The below example runs the same code on all maps on the page. It will then programatically set the map center over Canada and change the zoom level to 3.

$(document).on('loaded.mr.maps', function(evt){
  evt.map.setCenter(new google.maps.LatLng(62.2270,105.3809));
  evt.map.setZoom(3);
});