iamheremap.js - create a map for tracking lat/lon using ModestMaps
<html>
<head>
<title>I Am Here Map</title>
<script type="text/javascript" src="iamheremap.js"></script>
<script>
$(document).ready(function(){
var args = {
'modestmaps_provider' : 'CloudMade',
'flickr_apikey' : 'YER_FLICKR_APIKEY',
'cloudmade_apikey' : 'YER_CLOUDMADE_APIKEY',
'map_style' : 999,
'enable_logging' : true,
};
window.map = new info.aaronland.iamhere.Map('iamheremap', args);
});
</script>
</head>
<body style="margin:0;">
<div id="iamheremap"></div>
</body>
</html>
I Am Here Map is a Javascript library to create and embedded map to find the latitude and longitude of a point, using the ModestMaps Javascript API.
It also supports geocoding, reverse-geocoding and automagic client positioning using a variety of geolocation providers as well as the ability to display shape contours for locations that have been reverse-geocoded.
It is heavily indebted to Simon Willison's original www.getlatlon.com website.
http://www.aaronland.info/iamhere/
modestmaps_provider (required)
Valid providers are :
CloudMade
Use map tiles provided by CloudMade. You will need a valid CloudMade API key.
See also: http://maps.cloudmade.com/
A MapProvider-derived class (instantiation) of your own
You may also specify a ModestMaps MapProvider-derived class of your own.
For example, to if you wanted to use OpenStreetMaps tiles:
info.aaronland.iamhere.OpenStreetMapsProvider = function() { com.modestmaps.MapProvider.call(this, function(coordinate) { var img = coordinate.zoom.toFixed(0) +'/'+ coordinate.column.toFixed(0) +'/'+ coordinate.row.toFixed(0) + '.png'; return 'http://tile.openstreetmap.org/' + img; }); }; com.modestmaps.extend(info.aaronland.iamhere.OpenStreetMapsProvider, com.modestmaps.MapProvider); var osm = new info.aaronland.iamhere.OpenStreetMapsProvider(); var args = { 'modestmaps_provider' : osm, // all your other args here }; window.map = new info.aaronland.iamhere.Map('map', args);
cloudmade_apikey
A valid CloudMade API key. Required if your modestmaps_provider is "CloudMade".
You can register for a CloudMade API at http://developer.cloudmade.com
map_style
A map style specific to the tile provider.
Required if your modestmaps_provider is "CloudMade" (use '999' for the spooky).
flickr_apikey
A valid Flickr API key.
Required for things like reverse geocoding and displaying location contours.
You can register for a Flickr API key at http://www.flickr.com/services/api/keys/apply/
latitude
The latitude where the map should be displayed on load.
The default is 0
longitude
The longitude where the map should be displayed on load.
The default is 0
zoom
The zoom level that the map should load with.
The default is 2
map_height
Default is 400.
map_width
Default is the width of the browser window.
auto_display_shapefiles
Automatically load and display Flickr shapefiles for a location. Obviously, this requires that you pass a valid Flickr API key and that a point be successfully reverse geocoded.
Default is false.
disable_query_args
I Am Here maps are set up to allow a limited number of config options to be read from query arguments, passed either as proper query arguments or in the hash component of the URL. These options take a higher precedence than those passed to the object constructor.
This flag will disable this feature. If true, this has the side-effect of disabling auto-generated (and updating) permalinks since there's not really any point, is there?
Default is false.
max_decimal_points
If not-null, trim the number of decimal points by this number when displaying latitudes and longitudes.
refresh_title
If true, refresh the page title with the current latitude and longitude (and place name if reverse geocoding was successful).
Default is false.
enable_logging
Write events and errors to console.log
Unless otherwise disabled, the following parameters may be passed as "starting" arguments. They will also be automatically updated in the hash (#) component of the URL whenever the map changes position.
latitude
Assign the latitude of the map's current center point.
longitude
Assign the longitude of the map's current center point.
zoom
Assign the map's current zoom level.
style
Shorthand for the 'map_style' argument, and included only if present in the original URL.
shapefiles
Shorthand for the 'auto_display_shapefiles' argument, and included only if present in the original URL.
If you pass a URL containing a real and proper query fragment it will be rewritten (and redirected) to the same URL with the arguments passed in the hash component. This is mostly to make "pretty" URLs even if they may not be technically "correct".
Geocoding addresses is performed using either the Google Maps geocoding (v3) API or the Flickr API, assuming the requisite libraries have been loaded and API keys defined.
The order of precedence for geocoding is:
Google Maps API
Version 3, and higher.
Flickr API
Using the flickr.places.find API method, which does not do street-level geocoding.
Reverse geocoding of points is performed using the Flickr API, assuming you've included a valid Flickr API key.
Positioning (or geolocating) of the current user is attempted using a variety of providers assuming the requisite libraries have been loaded and/or valid API keys have been defined.
The order of precedence for positioning is:
Loki/Skyhook API
Loki is first on the assumption that if you've passed a Loki API key then it's probably what you want to use; this may not hold true if you're using a browser/device with a built-in GPS unit but one step at a time.
Geode API
Firefox only.
Google Gears Geolocation API
Requires the Google Gears plugin/extension.
Google ClientLocation API
IP lookups.
The actual mechanics of the positioning logic are handled by the js-geolocation library.
This has only been tested in Firefox and Safari.
It should work in IE, but who knows...
The use (and size) of JQuery is probably overkill.
All things being equal it will probably be replaced with plain-vanilla native DOM calls in time.
The size and position of map (and the crosshairs) are fixed.
They still don't update correctly when the window is resized.
I haven't figured out packing/minifying for this yet.
It's probably just a missing cluebat but so far when I try I end up with weird Javascript errors.
* This uses a modified version of the 'mapcontrols-raphael.js' library.
I haven't gotten around to writing a proper patch yet against the ModestMap codebase yet..
Probably. Please to be gentle.
Aaron Straup Cope
Copyright (c) 2009 Aaron Straup Cope
This is free software. You may redistribute it and/or modify it under the same terms as Perl Artistic License.
http://en.wikipedia.org/wiki/Artistic_License
http://www.aaronland.info/weblog/2009/06/01/bubblegum/#iamhere
http://developer.cloudmade.com/
http://github.com/straup/js-iamheremap/