Maps


Requirements

Dependencies

Before we can use the Maps component, we must have the jquery-ui-map library installed.

You can check if it's already installed by looking for the bower_components/jquery-ui-map directory.

Install with Bower:

bower install jquery-ui-map --save

Copy the library:

Create a file .build/copy-vendor/copy.maps.google.json with the following content:

[
    {
        "task": "jquery-ui-map",
        "cwd": "bower_components/jquery-ui-map/ui",
        "src": "*",
        "dest": "js/vendor/maps/google/jquery-ui-map/ui"
    }
]

When running the build process, the json file will be picked up and executed automatically and it will copy all files and directories from the bower_components/jquery-ui-map/ui directory to the theme's build path in $BUILD_PATH/$THEME_NAME/js/vendor/maps/google/jquery-ui-map/ui.

Note that you don't have to load the jquery-ui-map library from HTML, as the Maps component will load it automatically.

JavaScript

To load the Google maps component, from src/js/themes/$THEME_NAME/app.js:

// Maps
window.initGoogleMaps = require('maps/js/google/main');

This will load lib/maps/js/google/main.js into our main application script bundle.

Note that we have to expose the global initGoogleMaps callback function which will be executed automatically by the Google Maps API when the maps libraries are loaded, which is why we attached it to window.

Less

From src/less/themes/$THEME_NAME/app.less:

// Maps
@import "maps/less/maps";

Which will load lib/maps/less/maps.less into our main application style bundle.


Alternative

If working with Less and Browserify bundles is not your favorite thing, you can alternatively load the pre-built static assets we have included:

<!-- In the head of the HTML document -->
<link rel="stylesheet" href="css/app/maps.css" />

<!-- At the bottom of the HTML document -->
<script src="js/app/maps.js"></script>

Initialization

We can initialize a new Google Map in HTML purely through the markup API without writing a single line of JavaScript:

<div data-toggle="google-maps"></div>

Options

We can pass various options to interact with the Google Maps component, also through the markup API (data attributes).

Zoom controls position

Default: TOP_LEFT

<div data-toggle="google-maps" data-zoom-position="TOP_LEFT"></div>

Zoom level

Default: 16

<div data-toggle="google-maps" data-zoom="16"></div>

Style

Default: light-grey

<div data-toggle="google-maps" data-style="light-grey"></div>

This actually loads and applies a custom map style from lib/maps/js/google/styles/_light-grey.js. To see all the available styles, have a look at the available files in the lib/maps/js/google/styles/ directory.

Map type

Default: ROADMAP

<div data-toggle="google-maps" data-type="ROADMAP"></div>

Draggable

Default: true

<div data-toggle="google-maps" data-draggable="true"></div>

Pagination

Adds pagination between markers.

Default: false

<div data-toggle="google-maps" data-pagination="true"></div>

Loading markers from a JSON file via AJAX

<div data-toggle="google-maps" data-file="markers.json"></div>

Center map to coordinates

<div data-toggle="google-maps" data-center="latitude,longitude"></div>

Events

map.init

Triggered when the maps are initialized and available. We can hook into this event to add functionality to our maps and further interact with Google Maps API.

For example, consider src/js/themes/$THEME_NAME/_maps.js:

(function($){
    'use strict';

    $(document).on('map.init', function(event, data){

        // We now have access to the initialized map(s)

        // To isolate custom functionality to a specific map, 
        // give the HTML element a unique ID, e.g:
        // <div data-toggle="google-maps" id="my_map"></div>
        // and to execute code only when #my_map is initialized:

        if (data.container.attr('id') == 'my_map') {
            // do something with #my_map
        }

        // Otherwise, do something when ANY map is initialized:

        // The container element
        console.log(data.container);

        // The google map object
        console.log(data.map);

        // The options
        console.log(data.options);

        // The google maps info window
        console.log(data.iw.window);

        // We can get the markers
        var markers = data.container.gmap('get', 'markers');
        console.log(markers);

        // We can add new Google Maps API event listeners
        google.maps.event.addListener(data.map, 'click', function (event) {
            // do something when a user clicks on the map
        });

        // Attach to the info window
        google.maps.event.addListener(data.iw.window, 'domready', function () {
            // do something with the info window, you have access to it's DOM
        });

    });

})(jQuery);

And we can load our custom functionality from src/js/themes/$THEME_NAME/app.js:

// Maps
window.initGoogleMaps = require('maps/js/google/main');

// Custom functionality
require('./_maps');

Marker images

We provide 8 custom marker sets of 10 markers each.

The marker images are located in lib/maps/images/markers.

Requirements

To use the marker images in your theme, you must copy the lib/maps/images/markers directory into your theme's build path in $BUILD/$THEME_NAME/images/markers.

We can automate this when running the build process.

Update .build/copy-vendor/copy.maps.google.json to include the following:

[
    {
        "task": "lib-maps-images",
        "cwd": "lib/maps/images",
        "src": ["**/*"],
        "dest": "images"
    }
]

The json file will be picked up and executed automatically when running the build process.

Usage

Now that we have the marker images available in our theme's build path in the $BUILD_PATH/$THEME_NAME/images/markers directory, we can use them to display markers directly from the JSON data with the icon key on each marker object set to the image file name without the extension:

{
    "markers": [
        {
            ...
            "icon": "building-02"
        },
        {
            ...
            "icon": "house-01"
        }
    ]
}

Popups

InfoBox

Our Google Maps component is using InfoBox, as an enhanced version of an InfoWindow. An InfoWindow displays content, usually text or images, in a popup window above the map, at a given location, typically attached to a marker. The InfoBox behaves like an InfoWindow, but it supports several additional properties for advanced styling. You can see more details on the official API reference.

Requirements

Dependencies

We must have the InfoBox library included with Google Maps utility library installed. You can check if it's already installed by looking for the bower_components/gmaps-infobox directory.

Install with Bower:

First, update the bower.json file to include gmaps-infobox in it's dependencies:

"dependencies": {
    "gmaps-infobox": "svn+http://google-maps-utility-library-v3.googlecode.com/svn#infobox"
}

Then install:

bower install

Copy the library:

Update .build/copy-vendor/copy.maps.google.json to include the following:

[
    {
        "task": "gmaps-infobox",
        "cwd": "bower_components/gmaps-infobox/1.1.13/src",
        "src": ["*.js"],
        "dest": "js/vendor/maps/google/jquery-ui-map/addons"
    }
]

The json file will be picked up and executed automatically when running the build process. It will copy all *.js files from the bower_components/gmaps-infobox/1.1.13/src directory into the theme's build path in $BUILD_PATH/$THEME_NAME/js/vendor/maps/google/jquery-ui-map/addons.

Note that you don't have to load the library from HTML, as the Maps component will load it automatically.

Templates

To customize the view of the InfoBox, we are using Handlebars templates. The Maps package provides several templates in lib/maps/html/_map_templates.html.

Before we can use the provided sample templates with the Maps component, we must include the templates from lib/maps/html/_map_templates.html in our HTML document. We can easily do that using Swig.

Consider a simple page in src/html/themes/$THEME_NAME/maps.html:

{% extends "src/html/themes/$THEME_NAME/_layout.html" %}

{% block content %}

    <!-- The Maps -->
    <div data-toggle="google-maps" data-file="js/google_maps/data/markers.json"></div>

    <!-- Templates -->
    {% include "lib/maps/html/_map_templates.html" %}

{% endblock %}

After running the build process, the templates will be included in your theme's build path, in $BUILD_PATH/$THEME_NAME/maps.html:

<script id="map-infobox-icon" type="text/x-handlebars-template">
    <div>
        <div class="text-center">
            <div class="h1 text-grey-300">
                <i class="{{ inner_icon }}"></i>
            </div>
            <p><a href="#" class="h4 text-primary">{{ name }}</a></p>
            <p>{{ description }}</p>
        </div>
    </div>
</script>

<script id="map-infobox-simple" type="text/x-handlebars-template">
    <div>
        <div class="text-center">
            <h1>{{ title }}</h1>
            <p>{{ description }}</p>
        </div>
    </div>
</script>

Usage

Note that each template has a unique id attribute. We'll use the id within the JSON data to instruct the Maps component to use a specific template when displaying the popup window attached to each marker, using the template key from the marker object.

Consider the following JSON data file in js/google_maps/data/markers.json:

{
    "markers": [
        {
            "latitude": 57.698920689483,
            "longitude": 11.983367179871,
            "title": "A Building",
            "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit.",
            "template": "map-infobox-simple",
            "icon": "building-02",
            "open": true
        },
        {
            "latitude": 57.698656963659,
            "longitude": 11.977981304198,
            "name": "A House",
            "inner_icon": "fa fa-home",
            "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit.",
            "template": "map-infobox-icon",
            "icon": "house-01"
        }
    ]
}

This will add 2 markers on the map, using different templates for displaying popup windows attached to the markers.


Demo data

Additionally, you can also copy the demo JSON data into your theme's build path.

Update .build/copy-vendor/copy.maps.google.json to include the following:

[
    {
        "task": "lib-maps-data",
        "cwd": "lib/maps/js/data",
        "src": "*.json",
        "dest": "js/data/google_maps"
    }
]

This will copy all *.json files from the lib/maps/js/data directory into your theme's build path in the $BUILD_PATH/$THEME_NAME/js/data/google_maps directory, when running the build process.

Now you can load the demo JSON data:

<div data-toggle="google-maps" data-file="js/data/google_maps/markers.json"></div>