Description
This widget draws an interactive Google map with multiple address markers. Each marker contains information about its location.
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 Marker 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 GoogleMarkerMap 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}GoogleMarkerMap
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 array with each element in the array describing a marker to place on the drawn map.
Each element in the array contains includes a locationRequest key, the value of which 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 : Defining three markers using a precise address
function getData()
{
return [
{
locationRequest : { address : "Unit 4, Ebase Technology Ltd, St Georges Tower, Hatley St George, Sandy SG19 3SH, UK" },
locationInformation : "<h4>Ebase Technology Ltd</h4><br/>Unit 4<br/>St Georges Tower<br/>Hatley St George<br/>Sandy<br/>SG19 3SH<br/>UK<br/><a href='https://verj.io'>Verj.io Website</a>",
centerOnLocation : true
},
{
locationRequest : { address : "Cambridge Railway Station, Station Rd, Cambridge CB1 2JW, UK" },
locationInformation : "<h4>Cambridge Railway Station</h4><br/>Station Rd<br/>Cambridge<br/>CB1 2JW<br/><a href='http://www.nationalrail.co.uk/stations/CBG/details.html'>National Rail Website</a>",
},
{
locationRequest : { address : "Sandy Railway Station, Station Road, Sandy SG19 1AF, UK" },
locationInformation : "<h4>Sandy Railway Station</h4><br/>Station Rd<br/>Sandy<br/>SG19 1AW<br/><a href='https://www.greatnorthernrail.com/travel-information/plan-your-journey/station-information/stations/sandy?utm_content=station-code-SDY'>Great Northen Rail Website</a>",
}
];
}
This produces a map with 3 address marked on it. All three markers have information which will pop up when the marker is clicked on. The map is centered on the first location.
Example 2 : Adding images from the workspace to the information
Step 1: Add the image to the workspace.
Create a ServerResources folder (or use an existing one) and add the image to it - in this case we added a verj_io.png image file.
See ebase documentation for more information about ServerResource folders.
Step 2: We can configure the locationInformation to point to this image.
function getData()
{
return [
{
locationRequest : { address : "Unit 4, Ebase Technology Ltd, St Georges Tower, Hatley St George, Sandy SG19 3SH, UK" },
locationInformation : "<img src='verj_io.png' align='right'/><br/><h4>Ebase Technology Ltd</h4><br/>Unit 4<br/>St Georges Tower<br/>Hatley St George<br/>Sandy<br/>SG19 3SH<br/>UK<br/><a href='https://verj.io'>Verj.io Website</a>",
centerOnLocation : true
}
];
}
Additional Notes
The map is created within a jQuery ready event on the GoogleMarkerMap Panel Control. This means the map is shown when the page is displayed.
To prevent this you can hide the GoogleMarkerMap 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}GoogleMarkerMap.show();