kkemple/backbone.googlemaps

A Backbone JS extension for interacting with the Google Maps API (v3.10)

Backbone.GoogleMaps

A Backbone JS extension for interacting with the Google Maps API (v3.10)

A note regarding the future of Backbone.GoogleMaps

I am currently working on a Backbone.Maps v2.0 update to the libary with better separation of concerns, support for multiple mapping APIs, expanded overlay view support, and (shocking) unit tests.

I apologize for my slow response to pull requests. One of the reasons I've been slow to respond to pull requests is that I haven't been able to run tests to check that new and existing functionality is functional. (A full-time job and a toddler at home might have something to do with my slow response, too, now that I think of it.)

I am glad so many people have found this library useful. If you are interested in supporting the transition to v2.0, I would love to find some collaborators to help me kickstart the project. You can find my contact info in my user profile

About backbone.googlemaps

Backbone.GoogleMaps is a simple Backbone JS extension for simplified interactions with the Google Maps API. The motivation for creating this extension was to have an easy way to sync data about maps locations from a database with the Google Maps UI, using Backbone's RESTful interface.

Example

View the files in the example directory for working samples. Don't forget to add your Google Maps API key:

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

A simple example:

// Create Google map instance
var places = new Backbone.GoogleMaps.LocationCollection([
	{
		title: "Walker Art Center",
		lat: 44.9796635,
		lng: -93.2748776
	},
	{
		title: "Science Museum of Minnesota",
		lat: 44.9429618,
		lng: -93.0981016
	}
]);

var map = new google.maps.Map($('#map_canvas')[0], {
	center: new google.maps.LatLng(44.9796635, -93.2748776),
	zoom: 12,
	mapTypeId: google.maps.MapTypeId.ROADMAP
});

// Render Markers
var markerCollectionView = new Backbone.GoogleMaps.MarkerCollectionView({
	collection: places,
	map: map
});
markerCollectionView.render();

Backbone.GoogleMaps Components

Backbone.GoogleMaps is packaged with several customizable components.

GoogleMaps.Location

Represents a lat/lng location on a map. Extends Backbone.Model.

Properties

Property	Default Value	Description
lat	0	The location's latitude
lng	0	The location's longitute
selected	false	A flag for selecting a location
title	""	Location title

Methods

Method	Parameters	Return Value	Description
select			Sets the model's selected property as true. Triggers a "selected" event on the model.
deselect			Sets the model's selected property as false. Triggers a "deselected" event on the model.
toggleSelect			Toggles the model's selected property.
getLatLng		google.maps.LatLng instance	Returns the latitude and longitude of the model

GoogleMaps.LocationCollection

A collection of GoogleMaps.Location objects. Extends Backbone.Collection.

Only a single Location model can be selected in a given LocationCollection at any time.

GoogleMaps.MapView

A generic GoogleMaps view, for controlling a maps overlay instance. Extends Backbone.View.

Properties

Property	Default Value	Description
map		The google.maps.Map instance to which the overlay is attached
mapEvents	{}	Hash of Google Map events. Events are attached to this.gOverlay (google map or overlay)
gOverlay	this.map	The overlay instance controlled by this view
overlayOptions	{}	Properties set on this.gOverlay upon creation of the google maps overlay instance

Methods

Method	Parameters	Return Value	Description
bindMapEvents	mapEvents (optional)		Attaches listeners for the events in the mapEvents hash to this.gOverlay

GoogleMaps.InfoWindow

View controller for a google.maps.InfoWindow overlay instance. Extends GoogleMaps.MapView.

Properties

Property	Default Value	Description
gOverlay	Instance of google.maps.InfoWindow	The instance of the Google maps InfoWindow controlled by this view
marker (REQUIRED)		The marker associated with this.gOverlay
template	"<h2><%=title %></h2>"	A selector string for a template element

Methods

Method	Parameters	Return Value	Description
render		this	Instantiates a google.maps.InfoWindow object, and displays it on this.map

GoogleMaps.MarkerView

View controller for a marker overlay. Extends GoogleMaps.MapView.

Properties

Property	Default Value	Description
gOverlay	Instance of google.maps.Marker	The instance of the Google maps Marker overlay controlled by this view
infoWindow	GoogleMaps.InfoWindow	The InfoWindow view class used to when opening an infoWindow for this marker

Methods

<tr>
	<td>toggleSelect</td>
	<td></td>
	<td></td>
	<td>A pass-through to this.model.toggleSelect()</td>
</tr>
<tr>
	<td>render</td>
	<td></td>
	<td>this</td>
	<td>Sets as visisible this.gOverlay (the marker instance itself is created in the constructor)</td>
</tr>
<tr>
	<td>openDetail</td>
	<td></td>
	<td></td>
	<td>opens the InfoWindow associated with this marker</td>
</tr>
<tr>
	<td>closeDetail</td>
	<td></td>
	<td></td>
	<td>closes the InfoWindow associated with this marker</td>
</tr>

Method	Parameters	Return Value	Description
refreshOverlay			Updates the position of the marker view on the map

GoogleMaps.MarkerCollectionView

View controller for a collection of GoogleMaps.MarkerView instances. Extends Backbone.View.

Properties

Property	Default Value	Description
markerView	GoogleMaps.MarkerView	The MarkerView view class used to when creating child MarkerView instances
map		The google.maps.Map instance to which the overlay is attached

Methods

Method	Parameters	Return Value	Description
render	collection (optional - defaults to this.collection)		Renders and displays MarkerViews for each model in this.collection
closeChildren			Removes all child MarkerView views
closeChild	child (Location model, or MarkerView instance)		Closes a single child MarkerView instance
addChild	child (Location model)		Renders and displays a single MarkerView
refresh			Closes all child MarkerView instances, and opens new instances