jQuery Store Locator Plugin

March 11th, 2012 5 minute read

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 and will be in the /dist directory

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. You will need to geocode your locations beforehand or use a geocoding API service if you want to try to do it on the fly. The reason for this is that all free geocoding APIs have strict limits that would easily be exceeded. In the end, you’re much better off storing the coordinates versus having to look them up for each location on each request.

A note on the distance calculation: this plugin currently uses a distance function that I found on the blog of 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. For v2 I also tried experimenting with the Directions API to request distances but also found the limits to be too restrictive. So, the distance calculation is “as the crow flies” instead of a road distance calculation. However, if you use the inline directions option that does provide the distance that’s returned via the directions request.

Last, it’s very important to note that the plugin requires the Handlebars template engine. This separates the markup of the infowindows and location list elements so that they can easily be restructured. Handlebars pretty slick, will read Mustache templates, and the built-in helpers 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

It is much easier to maintain the current list of options on GitHub vs. a gigantic HTML table, which is why I’m now including the options.md file in the repository. If you need to view options for a previous version please view the old options page.

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="assets/css/storelocator.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="https://code.jquery.com/jquery-1.11.2.min.js"></script>

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

<script src="assets/js/libs/handlebars.min.js"></script>

4. Create a new Google Maps API key and make sure to enable Google Places API Web Service, Google Maps Geocoding API and Google Maps Directions API for the project in the Google API Console after setting up the initial Maps key.

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

<script src="https://maps.google.com/maps/api/js?key=yourkey"></script>

Region targeting example:

<script src="https://maps.google.com/maps/api/js?key=yourkey&region=UK"></script>

6. Include the plugin file:

<script src="assets/js/plugins/storeLocator/jquery.storelocator.js"></script>

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

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

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

Geocoding:

To geocode all your locations you can use a free or paid 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 with MySQLi and use something such as:

$results = $db->query("SELECT * FROM locations");
$locations = array();

foreach($results as $location){
	array_push($locations, $location);
}

//Output JSON
echo json_encode($locations);

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

Support:

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

Download on GitHub

Tutorials

Cardinal Store Locator

Donations

Some people have asked to donate. Feel no obligation but if you want to my Paypal email is bjorn2404@gmail.com and I also have a Bitcoin address set up: 17ueYyfaxCyEXedecVnr3w7GjM9PJD4CHj

Special thanks

My initial motivation for creating this jQuery plugin was a custom implementation request of my older JavaScript locator for Phin & Phebes Ice Cream. If you’re on the east coast be sure to seek out a pint.

Oops! We could not locate your form.

Posted in Web | 1,420 Comments