jQuery Store Locator Plugin

I can’t believe it’s been over a year since I first published my Google Maps store locator JavaScript code. I’ve had several requests for an updated version and that post has definitely received more traffic than any of my others. I’ve finally created a new version of the locator using Google Maps API version 3 and this time I’ve turned it into a full-on jQuery plugin. I re-worked almost everything in the code but I don’t think I’m going to go through function by function like I did in the last post. jQuery should make this store locator much easier to implement and I’ve included several options. Without further ado, here is the full documentation for the plugin:

jQuery Google Maps Store Locator Plugin

Files can be downloaded from GitHub

This jQuery plugin takes advantage of Google Maps API version 3 to create an easy to implement store locator. No back-end programming is required, you just need to feed it KML, XML, or JSON data with all the location information. How you create the data file is up to you. I originally created this for a company that didn’t have many locations, so I just used a static XML file. I also decided to geocode all the locations beforehand, to make sure it was quick and to avoid any potential geocoding errors. However, if you’re familiar with JavaScript you could easily make a modification to geocode everything on the fly (I may add this as an option at some point).

A note on the distance calculation: this plugin currently uses a distance function that was originally programmed by Chris Pietschmann. Google Maps API version 3 does include a distance calculation service (Google Distance Matrix API) but I decided not to use it because of the current request limits, which seem somewhat low. In addition, because the plugin currently calculates each location’s distance one by one, it appeared that I would have to re-structure some things to make all the distance calculations at once (or risk making many request for one location lookup). So, the distance calculation is “as the crow flies” instead of a road distance.

Handlebars is now required: It’s very important to note that the plugin now requires the Handlebars template engine. I made this change so that the data that’s displayed in the location list and the infowindows can be easily customized. I also wanted to separate the bulk of the layout additions from the main plugin file. Handlebars pretty slick, will read Mustache templates, and the built-in helpers can really come in handy. Depending on what your data source is, 2 of the 4 total templates will be used (KML vs XML or JSON) and there are options to set the paths of each template if you don’t want them in the default location. If you’re developing something for mobile devices the templates can be pre-compiled for even faster loading.

Options

The following options are available.

Usage:

Assuming you already have your locations.xml file set up in the current directory and the basic HTML copied from the example index file, the following would be the simplest usage example:

1. Include the css file (you’ll most likely want to make modifications to this beforehand):

<link rel="stylesheet" type="text/css" href="css/map.css">

2. Include jQuery if you don’t have it on your page already (the example below uses the Media Temple CDN but you can load it from wherever you’d like):

<script src="http://code.jquery.com/jquery-1.9.1.min.js"></script>

3. Include the latest version of Handlebars.js (this is now required)

<script src="js/handlebars-1.0.rc.1.min.js"></script>

4. Include Google Maps API. If you want to target a particular country add “&region=” to the end of the URL followed by the country code.

<script src="http://maps.google.com/maps/api/js?sensor=false"></script>

Region targeting example:

<script src="http://maps.google.com/maps/api/js?sensor=false&region=UK"></script>

5. Include the plugin file:

<script src="js/jquery.storelocator.min.js"></script>

6. Apply the storeLocator plugin to the map-container div.

<script>
  $(function() {
    $('#map-container').storeLocator();
  });
</script>

7. Make sure you have the basic form and map container HTML set up or copied from the example file.

Geocoding:

If you want to geocode your locations beforehand like I did, you can use a free service or use the geocode.html that I included. This provides a basic form and will use the Google Maps API to give you the latitude and longitude of the location you input.

JSON (optional):

I’ve added JSON support as an option with version 1.2 of the plugin, which is completely optional. The JSON file included in the GitHub repository is just there as an example. The file was generated via PHP from a MySQL database. The database structure I used for the example is pictured in the following image:

Outputting the JSON from the database is extremely simple with PHP. Make the database connection and use something such as:

$results = mysql_query('SELECT * FROM locations');
$rows = array();
while($r = mysql_fetch_assoc($results)) {
$rows[] = $r;
}
echo json_encode($rows);

Then you’d just set the dataLocation setting in the plugin directly to the PHP file.

Support:

I’ll try to answer basic questions and create more examples but my time is limited.

• Demo example
• Modal window example
• Default location example
• HTML5 auto geocode example
• KML example
• JSON example
• Maximum distance example
• No form tags example
• XML format example for location data

Download on GitHub