martimiz / silverstripe-googledirections

Dynamically add a GoogleMap and Google Directions to a page

Google map and directions module for SilverStripe CMS

Introduction

Create one or more Google Maps per page including (optional) Google directions from the user's location to your location. Define one map as the default map that displays on the on startup. Or create multiple links on the page, dynamically loading different maps, each with their own info on clicking the marker

You can simply create the dynamic links from the CMS using shortcodes or create links and optional JavaScript manually. The module is fully localized and backwards compatible to the old stable version 0.1

New in this version

• Create maps from within the CMS for each page
• Set a map as default, to display on page startup
• Add text and images to display on clicking the locator
• Use shortcodes to create dynamic links to switch between maps
• Disable directions (globally)

Other options

• Use the browser language or the current locale (default) to display directions
• Create dynamic links manually
• Use custom JavaScript
• Use geolocation or a valid address to generate maps
• Supports Translatable

Requirements

• SilverStripe Framework 3.1+ and CMS 3.1+

Installation

Copy the module to the root of your SilverStripe installation and give it any name you want.

Setting up the module

Enable the GoogleDirections extension on the page controller of the page type you want to display the map on. In _config/googledirections.yml:

Page:
  extensions:
    - GoogleDirections

Or use anothe pagetype. Then add the following to the template at the location where your map should go:

$GoogleDirections

Now do a /dev/build/?flush=1

If you want to use dynamic Shortcode links, in your _config.php set:

ShortcodeParser::get('default')
->register('GMap', array('GoogleDirections', 'link_shortcode_handler'));

Then perform a mydomain/?flush=all

Creating maps

Your page should now have a new tab 'Maps', where you can create one or more maps, using either a geolocation or a valid address. Note: geolocation takes presedence over address.

Default map

By checking 'Show when page is opened'in the Map details, that map becomes the default that will be displayed on opening the page.

Creating links for different maps

You can create links on the page that will dynamically open a specific map. If you have one or more links on the page, you do not necessarily have to

The easy way to create links is to use shortcodes. First you need to enable the use of shortcodes by adding this to your _config.php:

ShortcodeParser::get('default')
->register('GMap', array('GoogleDirections', 'link_shortcode_handler'));

Now create a shortcode, using the title of the map as a reference. The following will create a link where the title of the map is also the text of the link.

[GMap, link='My map title']

If you want to define a different text for the link:

[GMap, link='My map title']Text to appear in the link[/GMap]

Note: to create links manually, see advanced use: create links manually

Localization and i18n

The PHP code as well as the JavaScript in this module is localized. Find the language files here:

• For PHP: /lang/
• For JavaScript: /javascript/lang/

Note: the translation for origin needs to be equal in both javascript and PHP language file for the placeholder to work. I'm not sure if a placeholder attribute should be used instead, since there would be no other info in browsers that don't support this.

Enable/disable directions

By default directions are enabled for the module. Whenever a map is displayed, there is also a form where the user can enter his location, to calculate the route and display directions. You can however disable this, and only display the map. in _config/googledirections.yml:

GoogleDirections:
  directions_enabled: false

Directions language

By default the module will use the current SilverStripe locale to display directions, which is useful on multilingual sites. To revert to the current browser locale instead (Google default), add the following to your GoogleDirections.yml:

GoogleDirections:
  use_browser_language: true 

When using this module with the Translatable module, it might be better disable the use of the browserlanguage

Note: you may need to add this to your Page_Controller for the translations to work properly:

public function init() {

	i18n::set_locale($this->Locale);
	...
}

Advanced use: create links manually

Links should have the class 'googleDirections' to be automatically spotted by the module. The location for each link should be either a geolocation or a valid address. If both are present, the geolocation is used.

If you want to create a link manually, for instance in a template, it should look like this:

<a class="GoogleDirections" data-address="Street 22 Town" data-info="My company">Show map</a>

or

<a class="GoogleDirections" data-latlngs="'52.111111, 4.111111'" data-info="My company">Show map</a>	

Note: you do not have to create any maps in the CMS for this to work, the module will use the data in the link

Use JavaScript

If you want to use JavaScript, instead of adding the data to the link itself, you can do this:

<a class="GoogleDirections" id="MyLink" href="#route">Show map</a>

and

$(document).ready(function() {	
	locations.MyLink = {
	infoText: '<p><strong>My Name</strong><br>My description</p>',
	address: 'My Address'
	};
	// define this link as the default (startup) map
	showStartupMap('MyLink');
});

or

$(document).ready(function() {	
	locations.MyLink = {
		infoText: '<p><strong>My Name</strong><br>My description</p>',
		latLng: '52.111111, 4.111111'
	};
}); 	

Troubleshooting

1. the default text in the point-of-origin input doesn't disappear on entering the field

The default text in the inputfield for the point of origin needs to be equal in both language files for it to work. (Need to find another way for this, or use a placeholder attribute)

If the right JavaScript locale isn't picked up, this can be fixed by adding the locale to the body tag like this:

<body lang="$ContentLocale">

Maintainers

• Martine Bloem (Martimiz)

silverstripe-googledirections's Issues

default link setting (so no link has to be clicked)

This would be an awesome feature.

multiple markers on one map

Maybe it's usefull to be able to put multiple markers on one map.