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.

Property Default Description
mapDiv map The div where the actual Google Map is displayed.
listDiv loc-list The div container around the location list.
formContainerDiv form-container The div container around the form.
formID user-location The ID of the input form.
inputID address The ID of the input field.
zoomLevel 12 The zoom level of the Google Map. Set to 0 to have the map automatically center and zoom to show all display markers on the map.
pinColor fe7569 The hex color of the makers (don’t use # if you override).
pinTextColor 000000 The text hex color of the markers (don’t use # if you override).
lengthUnit m The unit of length. Default is m for miles, change to km for kilometers.
storeLimit 26 The number of closest locations displayed at one time. Set to -1 for unlimited.
distanceAlert 60 Displays an alert if there are no locations with 60 miles of the user’s location. Set to -1 to disable.
dataType xml The format of the data source. Accepted values include kml, xml, json, and jsonp.
dataLocation locations.xml The path to the location data – XML is default but JSON is also an option.
listColor1 ffffff The hex background color of the odd list elements (don’t use # if you override).
listColor2 eeeeee The hex background color of the even list elements (don’t use # if you override).
originMarker false Display a marker at the origin.
originpinColor blue Sets the color of the origin marker.
bounceMarker true Bounces the maker when a list element is clicked.
slideMap true First hides the map container and then uses jQuery’s slideDown method to reveal the map.
modalWindow false Shows the map container within a modal window. Set slideMap to false and this option to true to use.
overlayDiv overlay The div that fills 100% of the window and fills with a transparent background image when the modal window option is used
modalWindowDiv modal-window The div container of the actual modal window
modalContentDiv modal-content The div container around the content of the modal window
modalCloseIconDiv close-icon The div that displays the close icon to close the modal window
defaultLoc false If true, the map will load with a default location immediately. Set slideMap to false if you want to use this.
defaultLat If using defaultLoc, set this to the default location latitude.
defaultLng If using defaultLoc, set this to the default location longitude
autoGeocode false Set to true if you want to use the HTML5 geolocation API (good for mobile devices)
maxDistance false Set to true if you want to give users an option to limit the distance from their location to the markers.
maxDistanceID maxdistance The ID of the select element for the maximum distance options.
fullMapStart false Set to true if you want to immediately show a map of all locations. The map will center and zoom automatically.
noForm false Set to true if you aren’t able to use form tags (ASP.net WebForms).
loading false Set to true to display a loading animated gif next to the submit button. Note, that if you don’t have a lot of location data, it may not even be shown because of the quickness.
loadingDiv loading-map The div that displays the loading animated gif.
featuredLocations false Set to true to enable featuring locations at the top of the location list (no matter the distance). Add featured=”true” to featured locations in your XML or JSON locations data
infowindowTemplatePath templates/infowindow-description.html The path to the default infowindow template.
listTemplatePath templates/location-list-description.html The path to the default list template.
KMLinfowindowTemplatePath templates/kml-infowindow-description.html The path to the KML infowindow template – used if dataType is set to kml.
KMLlistTemplatePath templates/kml-location-list-description.html The path to the KML list template – used if dataType is set to kml.
callbackBeforeSend null Callback
callbackComplete null Callback
callbackSuccess null Callback
callbackModalOpen null Callback
callbackModalClose null Callback
geocodeErrorAlert Geocode was not successful for the following reason: Language setting
blankInputAlert The input box was blank. Language setting
addressErrorAlert Unable to find address Language setting
autoGeocodeErrorAlert Automatic location detection failed. Please fill in your address or zip code. Language setting
distanceErrorAlert Unfortunately, our closest location is more than Language setting
mileLang mile Language setting
milesLang miles Language setting
kilometerLang kilometer Language setting
kilometersLang kilometers Language setting

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.10.1.min.js"></script>

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

<script src="js/handlebars-1.0.0.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.

Download on GitHub

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: 1BvHk9BxErFfc2n4Zcmu9As9Nh9YdAgYW5

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.