jQuery (Zepto) Geolocator

Features

jQuery Geolocator is a plugin that takes a list of addresses and gets a distance and directions to each address from your current geolocation position. If available, it uses W3C Geolocation API (HTML5 Geolocation) to find your current location, and queries Google Maps API for distances to each address inside your list. If the visitor's browser is old and does not support the Geolocation API, the more inaccurate IP address based geolocation from Google is used.

This plugin is a fork of / based on HTML5-GeoLocation-jQuery-Plugin by teleject.

Why did I decide to make a new plugin instead of using the old one?

At first I only wanted to add some options to the original plugin, and fix variables that were leaking into the global scope. I soon realized that there were far more things that I wanted change inside the plugin, so I ended up rewriting many parts of the plugin code.

Demo

Click here for a demo

Dependencies

To use the plugin the following scripts/libraries are required, and should be included on your page:

jQuery (requires at least version 1.6) or Zepto (needs a custom build like this rake concat[-detect:-form:data:selector:fx_methods] dist you can find the mentioned custom build inside the dist folder)
Google JS API + API key
Google Maps API

How to use

1. Markup

You need to wrap each address inside your list item with Microformats hCard ADR defined classes, and somewhere inside the list item an element that has distance as its classname (that is where the distance for that address is printed). Classnames used in default markup can be changed via plugin options.

Example markup:

<div id="locations">
<ul>
  <li>
    <div class="adr">
      <span class="street-address">2907 E MLK Jr Blvd.</span>, 
      <span class="locality">Austin</span>, 
      <span class="region">TX</span>, 
      <span class="postal-code">78702</span>
    </div>
    <div class="distance"></div>
  </li>
  <li>
    <div class="adr">
      <span class="street-address">Aleksanterinkatu 52</span>
      <span class="postal-code">00100</span>, 
      <span class="locality">Helsinki</span> 
      <span class="country-name">Finland</span>
    </div>
    <div class="distance"></div>
  </li>
</ul>
</div>

If you want, you can optionally set latitude and longitude of the address as data attributes to .adr elements, to get more accurate results:

<div class="adr" data-latitude="##.######" data-longitude="##.######">
...
</div>

You can also have multiple unordered list elements with different addresses inside your locations element. However, you should only have one instance of the plugin running, since running multiple instances of the plugin seems to be quite buggy.

2. Needed scripts

Before you use the plugin, make sure that you have jQuery (or Zepto), Google JS API, Google Maps and jQuery Geolocator plugin linked inside your <head> tag, or before your ending </body> tag (recommended).

<script src="//www.google.com/jsapi?key=YOUR_GOOGLE_API_KEY"></script>
<script src="//maps.googleapis.com/maps/api/js?sensor=true"></script>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.8.0/jquery.min.js"></script>
<script src="js/jquery.geolocator.js"></script>

3. Javascript

After you have all script tags included, you can call the plugin on a list (unordered list, ul - by default) with your custom options. (Remember to wrap your code in jQuery's or Zepto's .ready() function)

Here we are changing the plugin to use kilometers instead of miles:

<script>
$(document).ready(function() {
	$("#locations").geolocator({ distanceBigStr: 'km', distanceSmallStr: 'm' });
});
</script>

You can also use the plugin without manually including Google API script tags, but it is not recommended since it will slow down the time it takes to find geolocation/distances as it has to load the Google APIs after the plugin has been initialized. This can be done with the apiKey option:

<script>
$(document).ready(function() {
	$("#locations").geolocator({ apiKey: 'YOUR_GOOGLE_API_KEY' });
});
</script>

If you later need to refresh the plugin, you can call it again on the same element without any options:

$("#locations").geolocator();

Info about Zepto support

Default build of Zepto.js does not provide all the methods that are needed, so you need to build a custom version of Zepto.

This is the custom build of Zepto that you can find inside the dist folder:

rake concat[-detect:-form:data:selector:fx_methods] dist

Plugin options: General settings

Following options can be used to customize the plugin:

sorting

Set to false if you don't want addresses to be sorted by distance automatically. Default: true.

manualCheck

Set to true if you want to disable automatic geolocating, and let the user manually geolocate using a link. Default: false.

Example:

<a href="#" id="check">Check geolocation</a>

notificationStyle

A notification style for your 'getting geolocation...' text. 'fade' or 'show'. Default: 'show'.

apiKey

An Google API key is needed if you want the plugin to download all Google APIs for you. Default: null.

targetBlank

Set to true to open all 'Show directions' links in a new browser tab/window. Default: false.

debugMode

Set to true to enable debug mode. This mode logs all Geolocation and Google API errors to you browser's Javascript console. Default: false.

Plugin options: Elements

checkElem

Element selector (a link element) for manualCheck setting. Default: '#check'.

recheckElem

Element selector (a link element) to recheck geolocation. Default: '#recheck'.

geodataElem

Element that displays your own location. Default: '#geodata'.

notificationElem

Element that displays a 'getting geolocation...' notification when the plugin is running. Default: '.notification'.

listParentElem

Parent element for a list (usually ul or ol). Default: 'ul'.

listElem

Child element for list items. Default: 'li'.

distanceElem

Element that displays the distance for each address. Has to be a child of listElem element. Default: '.distance'.

geoAdrElem

Element that holds each address. Has to be a child of listElem element. Microformats hCard ADR defined classes. Default: '.adr'.

mapsLinkElem

Element that is appended to each list item. Has to be a child of listElem element. Default: '.maps-link'.

locationsElem

With this setting you can assign your main element like this $.geolocator({ locationsElem: '#locations' });. Default: null.

Plugin options: Language strings

You can change the default texts used by the plugin to your own language.

distanceBigStr

Language string for big distance (miles or kilometers). If default string miles is changed, kilometers will be used. Default: 'miles'.

distanceSmallStr

Language string for small distance (meters). Default: 'meters'.

distanceUnknownStr

Language string for unknown distance. Default: 'unknown'.

notFoundStr

Language string that is displayed when your location is not found. Default: 'Could not get your location'.

mapsLinkStr

Language string for a Google Maps link that is showed next to each address. Default: 'Show directions'.

Plugin options: W3C Geolocation API options

enableHighAccuracy

Set to true if you want to get the most accurate location estimate possible. Getting geolocation might take longer if enabled. Default: false.

timeout

The number of milliseconds to wait before timing out. Default: 6000 (6 seconds).

maximumAge

Amount of time in milliseconds that the geolocation result is cached. Default: 60000 (1 minute).

Custom events

The following events are triggered on the element that is running jQuery Geolocator:

'geolocator:fail' when getting geolocation (Geolocation API or Google) fails.
'geolocator:done' when the script has finished running, and getting geolocation was successful.
'geolocator:own-fail' when getting your own location failed.
'geolocator:own-done' when getting your own location was successful.

You can listen to the events by using for example jQuery's .on() (or .bind()):

$("#locations").on("geolocator:done", function(){
  // do something
});

Browser support

The script uses Geolocation API in newer browsers. A fallback to a IP address based geolocation from Google is used in older browsers. It should work in Internet Explorer 7+, Firefox, Safari, Chrome and Opera. Even though the browser support is quite good, the performance might not be that good in older desktop and mobile browsers.

Reporting issues and bugs

If something is not working for you or you find a bug, please open a new issue at the issues section.

Developer

Developed by Krister Kari.

License

This software is released under the MIT license

Changelog

1.0.4 (19.08.2012) - Added support for Zepto.js
1.0.3 (19.08.2012) - Added a workaround for Google API limitations and added Grunt as a build tool
1.0.2 (01.05.2012) - added clearTimeout to fix a bug in older browsers, and did a small change to link creation
1.0.1 (27.04.2012) - 'targetBlank' option for links, support for country names (.country-name) and small fixes to loops.
1.0.0 (20.04.2012) - Initial release

kristerkari / jQuery-Geolocator