Home

Basic Overview

The map data is stored in a relation on a GoogleMap object and managed with a MapField. The GoogleMap provides a number of methods for creating/accessing the map on the front end. The map is intended to display a single marker and lets you save the map position and zoom as well.

Basic code example:

<?php

class ContactPage extends Page {

	static $has_one = array(
		'Map' => 'GoogleMap'
	);

	function getCMSFields() {
		$fields = parent::getCMSFields();
		
		$fields->addFieldToTab('Root.Media', $mapField = MapField::create('Map', 'Map'));
		
		// add some helpful text
		$mapField->setRightTitle('Enter an address or click the map to place the marker');
		
		// set the map to the size it will appear on the site
		$mapField->setMapSize(300, 300);
		
		return $fields;
	}

}

Gives us:

MapField For CMS Users

You can place or move the marker by doing one of the following:

• Enter an address in a the search bar and click "Search".
• Click somewhere on the map
• Drag the marker (if it exists) to a new place

As well as marker location the map saves the current view position and zoom. The address is also saved but currently only used for generating the Google Maps link.

Changes are saved when the page is saved.

Google Maps API Key

The maps API key is optional. Google recommends using it to track API usage.

You can set it in _config.php

GoogleMap::config()->api_key = 'abc123';

or in config.yml

GoogleMap:
  api_key: 'abc123'

Have a look at the module's config.yml for all configuration options.

MapField

Set the placeholder text for the address search field:

$mapField->setAddressPlaceholder('enter address to place marker on the map');

Set the map object type (eg if you want to make a subclass of GoogleMap):

$mapField->setMapObjectClass('MyGoogleMap');

There are several ways to specify the size of the map:

// set both dimensions (height, width)
$mapField->setMapSize(300, 300);

// set dimensions separately
$mapField->setMapHeight(300);
$mapField->setMapHeight(300);

If you like you can specify min and max dimensions to better emulate the map's behaviour on the front end. To do that just replace one of the integer values with array(min, max):

// set both dimensions (height, width)
$mapField->setMapSize(array(300, 500), 200);

You can set a default map/state by manually creating a GoogleMap object and passing it to MapField:

$default = GoogleMap::create();
$default->CenterLat = -40;
$default->CenterLng = 120;
$default->Zoom = 4;

// you can pass a map to the constructor
$fields->addFieldToTab('Root.Media', $mapField = MapField::create('Map', 'Map', $default));

// or pass it to setMap()
$mapField->setMap($default);

Note that right now it will save the defaults as a new map on page save, even if it hasn't been edited (https://github.com/nathancox/silverstripe-mapfield/issues/3).

GoogleMap On The Front End

The GoogleMap can be accessed several ways on the page.

Regular Map

To embed a JavaScript powered map you can just render the GoogleMap object in a template:

		$Map

Or get more control over the markup as well:

		<% with Map %>
		<div class='google-map' data-map-settings='$toJSON'></div>
		$IncludeScripts
		<% end_with %>

The included googlemaps.js script uses the data-map-settings json to construct the map.

Including Scripts

$IncludeScripts above will include both the Google API script and the module's frontend javascript. They're also included if you just use $Map (see the GoogleMap.ss template).

You can disable that behaviour through config (eg if you want to include it with combine_files or use your own script):

# in your config.yml
GoogleMap:
  include_api_script: false
  include_frontend_script: false


// in your page's controller init()
Requirements::javascript(GoogleMap::api_script_src());
Requirements::javascript(GoogleMap::frontend_script_src());

Static Maps

You can get the URL of a static map image using getStaticMapLink()

<%-- Embed a map image 311 px square --%>
<img src='$Map.getStaticMapLink(311)' alt='' />

<%-- Embed a map image 500 px wide and 300px tall --%>
<img src='$Map.getStaticMapLink(500,300)' alt='' />

Google Maps Link

You can get a link to the map on Google Maps using the Link() method:

<a href='$Map.Link'>View on Google Maps</a>

Note that the link is just generated using the stored address, not the coordinates, centering or zoom used for the other maps. If you want more precise control then I suggest making a separate text field for copying and pasting a maps URL into.