Google Maps

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

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,
   };

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.

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>

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>

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.

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.

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.

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.

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>

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;

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);
});