Google Maps the jQuery Plugin Way

One of the most common feature requests from our clients is Google Map integration. On two projects recently I found myself creating very similar functionality: a map of points with links in a nearby list that activate the markers on the map. This seemed like an excellent opportunity to package up functionality into some sort of “module.” Given that jQuery is my framework of choice I decided to go the route of a jQuery plugin (see David’s recent post for the advantages of jQuery plugins).

My goal when crafting this plugin was to use the convention-over-configuration paradigm, yet allowing customization, and to have the data be embedded in the HTML, allowing for graceful degradation in the rare cases where Google Maps wouldn’t be compatible. This would also allow the javascript the end user would need to write to be very minimal; one line is the default case.

The requirements for the most recent project were simple enough:

1. Create a Google Map in a specific div.
2. Add markers for given locations.
3. Color the markers based on a category they are assigned to.
4. Center the map around the markers and set it to a reasonable zoom level.
5. When a link on the page for the location is clicked it should activate the marker and load the map info window with specific HTML.

Basic Usage

The most basic usage would be with HTML like this:

<div id="map"></div> <div id="map-side-bar"> <div class="map-location" data="{id: 2, point: {lng: -122.4391131, lat: 37.7729943}, category: 'restaurant'}"> <a href="#" class="map-link">Nopalito</a> <div class="info-box"> <p>The best authentic Mexican restaurant in San Francisco.</p> </div> </div> <div class="map-location" data="{id: 3, point: {lng: -122.4481651, lat: 37.8042096}, category: 'museum'}"> <a href="#" class="map-link">Exploratorium</a> <div class="info-box"> <p>A hands-on museum of science, art, and human perception in San Francisco.</p> </div> </div> </div> 

And Javascript like this:

$(document).ready(function(){ $('#map').jMapping(); }); 

Working with options

The one thing this code doesn’t take care of is how to color the markers based on the categories. Coloring markers can easily be done with the Google Maps utility library MapIconMaker. To get it functional we just change the Javascript to this:

$(document).ready(function(){ $('#map').jMapping({ category_icon_options: { 'restaurant': {primaryColor: '#E8413A', cornerColor: '#EBEBEB'}, 'museum': {primaryColor: '#465AE0', cornerColor: '#EBEBEB'}, 'default': {primaryColor: '#7CDF65'} } }); }); 

There’s a whole host of other options you can use to customize it. Most importantly you can set the selectors the plugin uses to find the locations, links, and the info box elements. There are even more examples and explanations available at its home on GitHub. That’s also where you can find the downloads, report issues, or fork the code.

In the future, I hope to add the ability to update the map, and other functionality that people request, as well as create some Rails helpers for integrating it into your views.

Look for more articles down the line here about how the plugin was designed and structured, and the way it’s tested.