NAME
iamheremap.js - create a map for tracking lat/lon using ModestMaps
SYNOPSIS
<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>
DESCRIPTION
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.
EXAMPLE
<http://www.aaronland.info/iamhere/>
OBJECT METHODS
new info.aaronland.iamhere.Map(args)
* 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
PERMALINKS AND QUERY ARGUMENTS
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
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
Reverse geocoding of points is performed using the Flickr API, assuming
you've included a valid Flickr API key.
POSITIONING
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.
KNOWN-KNOWNS
* 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..
BUGS?
Probably. Please to be gentle.
AUTHOR
Aaron Straup Cope
LICENSE
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
SEE ALSO
<http://www.aaronland.info/weblog/2009/06/01/bubblegum/#iamhere>
<http://www.modestmaps.com/>
<http://developer.cloudmade.com/>
<http://raphaeljs.com/>
<http://www.getlatlon.com/>
<http://github.com/straup/js-iamheremap/>
<http://github.com/straup/js-flickr-api/>
<http://github.com/straup/js-geolocation/>
