Google Maps

You are here.

Exposes the mapping functionality from the Google Maps JavaScript API V3.

Simplicity provides a set of widgets to help add maps to your pages.

simplicityGoogleMap
Wraps the Google Map object, used by the other Simplicity widgets.
simplicityGoogleMapResults
Adds a marker to the map for each item in the current page of search results.
simplicityGoogleMapBoundsCoordinator
Moves and scales the map to ensure all markers are visible.
simplicityGoogleMapBoundsTracker
Watches the map to expose its position as it is panned and zoomed.
simplicityGoogleGeocoder
Converts addresses to latitude/longitude using AJAX requests to Google.

To use a Google Map, you need to add the Google Maps script tag to the page. This is documented in the Getting Started section of the Developer's Guide over at Google.

To summarize their fine documentation, add a single script tag to the page:

<script type="text/javascript"
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=SET_TO_TRUE_OR_FALSE">
</script>

The API key is optional but recommended and well documented in the Getting Started section of the Developer's Guide over at Google.

Place the script tag at the bottom of the page, typically after the script tags that load jQuery and Simplicity. This way the rest of the Simplicity wigets can interact even if there are network delays loading the Google Maps API.

<html>
    <head>
        <link rel="stylesheet" href="path/to/simplicity.min.css">
    </head>
    <body>
        <div>
            <!-- page content goes here -->
        </div>
        <script src="path/to/jquery.min.js"></script>
        <script src="path/to/jquery-ui.min.js"></script>
        <script src="path/to/simplicity.min.js"></script>
        <script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false"></script>
    </body>
</html>

This widget acts as a container for the Google map object. It can automatically create a map or you can pass one in. Other simplicity widgets use this widget to locate the actual map object.

To create a map, first create a container div. Notice that we explicitly configure the width and height of this div. Failure to do so will result in a 0x0 map that is not visible.

<div id="example" style="width:400px; height:200px;"></div>

Then either create the map with the default options.

$('#example').simplicityGoogleMap();

Or pass in your own.

$('#example').simplicityGoogleMap({
    mapOptions: {
        center: new google.maps.LatLng(51.507, -0.128),
        zoom: 11,
        mapTypeId: google.maps.MapTypeId.ROADMAP
    }
});

You can then access the created map as you need to.

var map = $('#example').simplicityGoogleMap('map');
map.setZoom(2);

Example

To create a map, first create a holder div.

<div id="example" style="width:400px; height:200px;"></div>

Then create the map and pass it into the simplicityGoogleMap widget.

var map = new google.maps.Map($('#example')[0], {
    center: new google.maps.LatLng(40.748,-73.986),
    zoom: 11,
    mapTypeId: google.maps.MapTypeId.ROADMAP
});
$('#example').simplicityGoogleMap({
    map: map
});

Example

Places markers on the map for the current page of search results.

$('#example')
    .simplicityGoogleMap()
    .simplicityGoogleMapResults();
});

By default, this widget will listen to search response from the body element and expect to find coordinates in the latitude and longitude properties of the search results. You can override these defaults by setting the searchElement, latitudeField and longitudeField options.

The widget fires a simplicitygooglemapresultsmarker event which you can use to customize the generated map markers.

Example

        

Select a sample search response from 2, see the details in 3 and notice how the markers are updated in 1.

This event is triggered by simplicityGoogleMapResults whenever it creates a marker from a search result which is about to be added to the map. It gives you the opportunity to customize the marker before it is attached to the map or prevent it from being added.

$('#example').bind('simplicitygooglemapresultsmarker', function (evt, ui) {
    // Use different icons for exact and fuzzy matches.
    if (ui.row.exact) {
        ui.marker.setIcon('example/exact.png');
    } else {
        ui.marker.setIcon('example/fuzzy.png');
    }
});

The ui parameter to the event handler will be populated with an Object containing the following properties.

map
The google.maps.Map instance.
marker
The marker that has been created. Possibly a google.maps.Marker.
row
Metadata about the associated row in the search results. This is an Object containing the following properties.
id
The id of this search result.
exact
true is this is an exact match, false otherwise
score
The floating point relevance score for this result.
resultsIndex0
The 0-based position of this result in the entire result set. With a page size of 10, the first result on the first page would have value of 0, and the first result on the second page would have a value of 10.
index0
The 0-based position of this result within the current page. The first result will always have a value of 0.
index1
The 1-based position of this result within the current page. The first result will always have a value of 1.
properties
Optional property. When it exist it contains the properties for the current result as returned by the Discovery Search Engine. For example {"_id":"10","price":375000}.
highlighting
Optional property. When it exist it contains the highlighting response for the current result as returned by the Discovery Search Engine. For example {"description":"This is a <b>great</b> example"}.

Handles coordinating the visible map bounds between multiple widgets. Achieves this by firing a simplicitygooglemapboundscoordinatorcalculatebounds event which provides a vendor specific bounds object, listeners of this event are responsible for extending the bounds to include all the points they want to make visible. The simplicityGoogleMapResults widget automatically adds its markers to the bounds event.

To use this widget, simply attach it to the same DOM element as the map.

$('#example')
    .simplicityGoogleMap()
    .simplicityGoogleMapBoundsCoordinator();

You can listen to the simplicitygooglemapboundscoordinatorcalculatebounds event like so.

$('#example').bind('simplicitygooglemapboundscoordinatorcalculatebounds', function (evt, ui) {
    // Ensure the following point is visible.
    ui.bounds.extend(new google.maps.LatLng(39.436,-94.746));
});

The ui parameter to the event handler will be populated with an Object containing the following properties.

bounds
A google.maps.LatLngBounds instance that you can modify.

Example

Choose which shapes you want to include in the bounds calculation from 2, press 3 and notice how the map moves in 1.

Gives access to the map bounds in normalized and vendor specific form. Triggers a simplicitygooglemapboundstrackerbounds event whenever the map is moved or zoomed.

To use this widget, simply attach it to the same DOM element as the map.

$('#example')
    .simplicityGoogleMap()
    .simplicityGoogleMapBoundsTracker();

You can listen to the simplicitygooglemapboundstrackerbounds event like so.

$('#example').bind('simplicitygooglemapboundstrackerbounds', function (evt, ui) {
    // Do something with the bounds
    console.log('Map bounds:');
    console.log('    north', ui.bounds.north);
    console.log('    east ',  ui.bounds.east);
    console.log('    south', ui.bounds.south);
    console.log('    west ',  ui.bounds.west);
});
Map bounds:
    north 38.03040444840505
    east  -121.706669921875
    south 37.38723293115014
    west  -123.025029296875

The ui parameter to the event handler will be populated with an Object containing the following properties.

bounds
The bounding box of the map, as an Object containing the following properties.
vendor
google.maps.LatLngBounds
north
The north most boundary of the bounding box. For example 43.22544272252788.
east
The east most boundary of the bounding box. For example -67.58411407470629.
south
The south most boundary of the bounding box. For example 38.23413509208393.
west
The west most boundary of the bounding box. For example -82.96497344970629.
center
The center point the map, as an Object containing the following properties.
vendor
google.maps.LatLng
latitude
For example 43.22544272252788.
longitude
For example -67.58411407470629.

Example

Pan and zoom the map in 1 and notice how the bounds are updated in 2.

Wraps a google.maps.Geocoder to provide geocoding services, converting addresses to latitude and longitude coordinates.

To use this widget, simply attach it to a DOM element.

$('#example').simplicityGoogleGeocoder();

Then you can call the geocode method. Note that it takes two arguments, the first is the maps.google.GeocoderRequest and the second a callback function that can handle the response once complete.

var request = {
    address: 'the whitehouse'
};
$('#example').simplicityGoogleGeocoder('geocode', request, function (response) {
    console.log('Geocoded:');
    console.log('    address:  ', response.items[0].value);
    console.log('    latitude: ', response.items[0].latitude);
    console.log('    longitude:', response.items[0].longitude);
});
Geocoded:
    address:   The White House, President's Park, 1600 Pennsylvania Avenue Northwest, Washington, DC 20500, USA
    latitude:  38.89768309999999
    longitude: -77.03649719999999

Example

Enter an address into 1, press enter or click outside the input and view the geocoded response in 2.

The simplicityGoogleMapGeocode widget can also act as a jQuery UI autocomplete source.

To set this up.

<input name="address" />
$('#example').simplicityGoogleGeocoder();
$('input').autocomplete({
    source: $('#example').simplicityGoogleGeocoder('autocompleteSource');
});

You could then listen for autocompletechange events to process the user's selection.

$('input').bind('autocompletechange', function (evt, ui) {
    // Process the selection
    console.log('ui', ui);
});

Example

Slowly type an address into 1. Once you select an option and press enter or click outside of the input, the autocompletechange event's ui argument is placed into 2.