Documentation

Google Map

Overview

The Google Maps field creates an interactive map with the ability to place a marker. This field features a search input, location finder button and click even to find and place the marker. The data saved and returned is an array containing the markers lat, lng, and address.

Creating a Google Map field

The Google Map field contains options to customize your field:

  • Center: Enter a default lat and lng value to center the map on a desired location when no marker has been saved
  • Height: Set a custom height for the map. This is useful for making a smaller sized map for use as a sub field

acf-google-maps-field-settings

Using a Google Map field

Without value

acf-google-maps-field-1

When the Google Map field is first loaded without a value set, the map will be centered on the lat/lng settings for the field. By default, this centers to the city of Melbourne, Australia.

To place the marker, you can either:

  • Search for an address and select 1 of the suggested results, or hit enter
  • Click on the ‘find my location’ button in the top right (Geo-locating services must be enabled on the browser for this to work correctly)
  • Click on the map where you wish the marker to be placed

With a value

acf-google-maps-field-2

Once a marker has been added, you will notice that the search and ‘find my location’ buttons are replaced with the marker’s address and a button to remove the value.

To edit the marker, you can either:

  • Click on the address title and edit it manually
  • Click on the clear value button to remove the marker completely
  • Drag and Drop the marker to replace it
  • Click on the map where you wish the marker to be moved to

Code Examples

The following code examples show how to use a single Google Map field to render a marker onto a map, and also how to use a repeater field along with the Google Map field to render multiple markers onto a map with infoWindows.

Both examples below require the following CSS and JS to be available to the page template. Please note that both the CSS and JS can be modified to your linking, however they are a good starting point to understand how the PHP data can be translated through HTML into the JS Google Map API.

Please also note that the Google API is required for this to work and is included in the required JS below. The Google Map API is a great library to render a map, however, it is not the only API available. Please consult Google for any other API’s and tutorials.

Required CSS & JS

<style type="text/css">

.acf-map {
	width: 100%;
	height: 400px;
	border: #ccc solid 1px;
	margin: 20px 0;
}

</style>
<script src="https://maps.googleapis.com/maps/api/js?v=3.exp&sensor=false"></script>
<script type="text/javascript">
(function($) {

/*
*  render_map
*
*  This function will render a Google Map onto the selected jQuery element
*
*  @type	function
*  @date	8/11/2013
*  @since	4.3.0
*
*  @param	$el (jQuery element)
*  @return	n/a
*/

function render_map( $el ) {

	// var
	var $markers = $el.find('.marker');

	// vars
	var args = {
		zoom		: 16,
		center		: new google.maps.LatLng(0, 0),
		mapTypeId	: google.maps.MapTypeId.ROADMAP
	};

	// create map	        	
	var map = new google.maps.Map( $el[0], args);

	// add a markers reference
	map.markers = [];

	// add markers
	$markers.each(function(){

    	add_marker( $(this), map );

	});

	// center map
	center_map( map );

}

/*
*  add_marker
*
*  This function will add a marker to the selected Google Map
*
*  @type	function
*  @date	8/11/2013
*  @since	4.3.0
*
*  @param	$marker (jQuery element)
*  @param	map (Google Map object)
*  @return	n/a
*/

function add_marker( $marker, map ) {

	// var
	var latlng = new google.maps.LatLng( $marker.attr('data-lat'), $marker.attr('data-lng') );

	// create marker
	var marker = new google.maps.Marker({
		position	: latlng,
		map			: map
	});

	// add to array
	map.markers.push( marker );

	// if marker contains HTML, add it to an infoWindow
	if( $marker.html() )
	{
		// create info window
		var infowindow = new google.maps.InfoWindow({
			content		: $marker.html()
		});

		// show info window when marker is clicked
		google.maps.event.addListener(marker, 'click', function() {

			infowindow.open( map, marker );

		});
	}

}

/*
*  center_map
*
*  This function will center the map, showing all markers attached to this map
*
*  @type	function
*  @date	8/11/2013
*  @since	4.3.0
*
*  @param	map (Google Map object)
*  @return	n/a
*/

function center_map( map ) {

	// vars
	var bounds = new google.maps.LatLngBounds();

	// loop through all markers and create bounds
	$.each( map.markers, function( i, marker ){

		var latlng = new google.maps.LatLng( marker.position.lat(), marker.position.lng() );

		bounds.extend( latlng );

	});

	// only 1 marker?
	if( map.markers.length == 1 )
	{
		// set center of map
	    map.setCenter( bounds.getCenter() );
	    map.setZoom( 16 );
	}
	else
	{
		// fit to bounds
		map.fitBounds( bounds );
	}

}

/*
*  document ready
*
*  This function will render each map when the document is ready (page has loaded)
*
*  @type	function
*  @date	8/11/2013
*  @since	5.0.0
*
*  @param	n/a
*  @return	n/a
*/

$(document).ready(function(){

	$('.acf-map').each(function(){

		render_map( $(this) );

	});

});

})(jQuery);
</script>

Render a single maker onto a map

This example shows how to use a single Google Map field to render out a map and marker onto the page.Each marker contains no inner HTML, so no infoWindow will be created (using the above JS)

<?php 

$location = get_field('location');

if( !empty($location) ):
?>
<div class="acf-map">
	<div class="marker" data-lat="<?php echo $location['lat']; ?>" data-lng="<?php echo $location['lng']; ?>"></div>
</div>
<?php endif; ?>

 

Render multiple markers onto a map

This example shows a repeater field (called ‘locations’) with 3 sub fields; title (text), description (textarea) and location (Google Map).

Each marker does contain inner HTML, so an infoWindow will be created (using the above JS)

<?php if( have_rows('locations') ): ?>
	<div class="acf-map">
		<?php while ( have_rows('locations') ) : the_row(); 

			$location = get_sub_field('location');

			?>
			<div class="marker" data-lat="<?php echo $location['lat']; ?>" data-lng="<?php echo $location['lng']; ?>">
				<h4><?php the_sub_field('title'); ?></h4>
				<p class="address"><?php echo $location['address']; ?></p>
				<p><?php the_sub_field('description'); ?></p>
			</div>
	<?php endwhile; ?>
	</div>
<?php endif; ?>