Google Location Map

Description

This widget draws an interactive Google map centered on a specific address. The map will load when the page is displayed.

Prerequisites

1. A recent version of the jQuery library is required in the target form or component. This widget has been tested to work with jQuery 1.12.4 and newer. Older versions may still work. Note that this widget does not work with the 'slim' version of the jQuery library. It is good practice to add this jQuery library to the target form's template. jQuery provides a CDN for their libraries - see https://code.jquery.com/

2. A Google Maps API key is required. See https://developers.google.com/maps/documentation/javascript/get-api-key. This API key will be used in the configuration section below and without an API key maps will not be drawn.

Installation

Using the Verj Studio, drag the 'Google Location Map' widget from the Widgets View onto the page where you want the map to appear. As part of installing this widget you will be asked to provide a widget prefix which acts as a namespace to it and seperates it from other widgets that may have been, or will be, added to the page.

During the installation process a GoogleLocationMap Panel Control is added to the page at the chosen location into which the Google map will be drawn. The Verj Studio is unable to display the map, it will however show in a browser. Before a map is drawn in the browser the widget needs to be configured; see the Configuration section below.

The following directory structure will be added to the 'Installed Widgets' Project (this project will be created if it does not exist already) during the installation process:

  InstalledWidgets
    GoogleLocationMap_{version}
      {formName}_{widgetPrefix}GoogleLocationMap
        Scripts
          configure

Configuration

Use the configure script (found in the 'Installed Widgets' project as shown in the directory structure above) to specify your API key, map display options and to specify the address to center on. This script has two functions config() and getData().

function config()

Returns a JSON object containing the display options for the map.

Importantly, the returned JSON object contains the API key to use. The API key in a newly installed widget is blank so the first task to carry out should be to add your API key to this JSON object. Maps will not appear until your API key is added.

The map's dimensions and display options can also be changed in this JSON object. 

Example 1: Interactive Map

function config()
{
    return {
        apiKey : 'MY API KEY',
        mapWidth : '100%',
        mapHeight : '400px',
        mapOptions : { zoom : 12 }
    };
}

This configuration draws an interactive google map. The key features of the JSON object are:

apiKey: Add your Google Maps API key here. No maps can be drawn without this key.

mapWidth: Set width of the map to 100%, so it will fill the width of its parent container.

mapHeight: The height of the map has been set to 400px.

mapOptions: This is where display options for the map can be added. See the google map options reference for more details about what options are available. Here we are specifying the initial zoom factor of the map - this is a range from 0 (the whole world) to 20.

Example 2: Fixed Map

function config()
{
    return {
        apiKey : 'MY API KEY',
        mapWidth : '100%',
        mapHeight : '400px',
        mapOptions: { zoom : 12, draggable : false, zoomControl : false, scrollwheel : false }
    };
}

This configuration prevents the user from moving or zooming the drawn map.

We have acheived this by disabling the draggability, zoom control and the mouse scroll wheel of the map in the MapOptions. This effectively fixes the map in position.

Example 3: Dark Interactive Map

function config()
{
    return {
        apiKey : 'MY API KEY',
        mapOptions: { zoom : 15,  styles : [ { featureType: "all", elementType: "all ", stylers: [ { invert_lightness : true } ] }] }
    };
}

All the colours in the map are inverted, producing a darker map.

The map will take on the dimensions of the GoogleMarkerMap Panel Control. It is equivalent to setting maxWidth:'100%' and maxHeight:'100%'.

function getData()

Returns a JSON object containing the initial location the map should center on and place a marker for. 

This JSON object has a single key; locationRequest. It is a JSON object representing a Google Geocoder Request (see Google Geocoder Request) and provides the full power of Google's address and lat/long search service.

Example 1 : Using a precise address

function getData()
{
	return { locationRequest : { address : "Unit 4, Ebase Technology Ltd, St Georges Tower, Hatley St George, Sandy SG19 3SH, UK" }	};
}

This widget uses the first result that Google returns so specifying an address precisely is important.

Example 2 : Narrowing searches to a specific country

function getData()
{
	return { locationRequest : { address : "Cambridge", componentRestrictions : { country: "UK" } }};
}

A way of displaying more relevant results to a general address search is to limit the scope of that search. Here we use Google's componentRestrictions to limit the search to the UK.

Additional Notes

The map is created within a jQuery ready event on the GoogleLocationMap Panel Control. This means the map is shown when the page is displayed.

To prevent this you can hide the GoogleLocationMap Panel Control in its Properties View.

Showing ths Panel Control, perhaps by using the on-click event of a Button Control, will then show the map. The following snippet could be used (the {widgetPrefix} should be replaced with the prefix given to the widget when installing it on the page) to show the Panel Control, and therefore the map, in the Button Control's on-click event:

controls.{widgetPrefix}GoogleLocationMap.show();