straup / js-iamheremap

A Javascript library to create and embedded map to find the latitude and longitude of a point, using the ModestMaps Javascript API.

This URL has Read+Write access

js-iamheremap / README
raw normal view history
e0491766 » straup 2009-05-31 initial commit 1 I Am Here Map is a Javascript library to create and embedded map to find the
2 latitude and longitude of a point, using the ModestMaps Javascript API.
3
4 It also supports geocoding, reverse-geocoding and automagic client positioning
5 using a variety of geolocation providers as well as the ability to display shape
6 contours for locations that have been reverse-geocoded.
7
8 It is heavily indebted to Simon Willison's original www.getlatlon.com website.
9
10 # EXAMPLE
11
12 <html>
13 <head>
14 <title>I Am Here Map</title>
15 <script type="text/javascript" src="iamheremap.js"></script>
16
17 <script>
18 $(document).ready(function(){
19 var args = {
20 'modestmaps_provider' : 'CloudMade',
21 'flickr_apikey' : 'YER_FLICKR_APIKEY',
22 'cloudmade_apikey' : 'YER_CLOUDMADE_APIKEY',
23 'cloudmade_style' : 999,
24 'find_my_location' : false,
25 'enable_logging' : true,
26 };
27
28 window.map = new info.aaronland.iamhere.Map('iamheremap', args);
29 });
30 </script>
31 </head>
32 <body style="margin:0;">
33 <div id="iamheremap"></div>
34 </body>
35 </html>
36
37 # CONSTRUCTOR ARGUMENTS
38
39 * modestmaps_provider (required)
40
41 It's not really, since there's only one tile provider (CloudMade) as of this
42 writing but some day there will be more so you might as well get used to being
43 specific about it.
44
45 * cloudmade_apikey (required)
46
47 A valid CloudMade API key.
48
49 Again, not really required except for the part where it is today.
50
1f00c457 » straup 2009-05-31 API sign up links 51 You can register for a CloudMade API at http://developer.cloudmade.com
52
e0491766 » straup 2009-05-31 initial commit 53 * cloudmade_style
54
55 A valid CloudMade API style identifier. Use '999' for the spooky.
56
57 Required if your 'modestmaps_provider' is CloudMade (which it is).
58
59 * flickr_apikey
60
61 A valid Flickr API key.
62
63 Required for things like reverse geocoding and displaying location contours.
64
1f00c457 » straup 2009-05-31 API sign up links 65 You can register for a Flickr API key at http://www.flickr.com/services/api/keys/apply/
66
e0491766 » straup 2009-05-31 initial commit 67 * find_my_location
68
69 Attempt to do automatic client geolocation on startup.
70
71 * enable_logging
72
73 Write events and errors to console.log
74
6e261e33 » straup 2009-05-31 map height/width 75 * map_height
76
77 Default is 400.
78
79 * map_width
80
81 Default is the width of the browser window.
82
e0491766 » straup 2009-05-31 initial commit 83 # GEOCODING
84
85 Geocoding addresses is performed using either the Google Maps geocoding (v3) API
86 or the Flickr API, assuming the requisite libraries have been loaded and API
87 keys defined.
88
89 The order of precedence for geocoding is:
90
91 * Google Maps API
92
93 * Flickr API
94
95 # REVERSE GEOCODING
96
97 Reverse geocoding of points is performed using the Flickr API, assuming you've
98 included a valid Flickr API key.
99
100 # POSITIONING
101
102 Positioning (or geolocating) of the current user is attempted using a variety of
103 providers assuming the requisite libraries have been loaded and/or valid API
104 keys have been defined.
105
106 The order of precedence for positioning is:
107
108 * Loki/Skyhook API
109
110 Loki is first on the assumption that if you've passed a Loki API key then
111 it's probably what you want to use; this may not hold true if you're using
112 a browser/device with a built-in GPS unit but one step at a time.
113
114 * Geode API (Firefox, only)
115
116 * Google Gears Geolocation API
117
118 * Google ClientLocation API (IP lookups)
119
120 The actual mechanics of the positioning logic are handled by the js-geolocation
121 library.
122
123 # KNOWN-KNOWNS
124
125 * This has only been tested in Firefox and Safari.
126
127 * The use (and size) of JQuery is probably overkill. All things being equal it
128 will probably be replaced with plain-vanilla native DOM calls in time.
129
130 * The size and position of map (and the crosshairs) are fixed and don't update
131 correctly when the window is resized.
132
5f8a0f4d » straup 2009-05-31 note about the zoom control 133 * If a shapefile is rendered too close to, or overlaps, the zoom controls
134 sometimes the zoom controls don't work.
135
e0491766 » straup 2009-05-31 initial commit 136 * I haven't figured out packing/minifying for this yet. It's probably just a
137 missing cluebat but so far when I try I end up with weird JS errors.
138
139 * This uses a slightly abused version of the ModestMaps 'mapcontrols-raphael.js'
140 library because I haven't gotten around to writing a proper patch yet.
141
142 # BUGS?
143
144 Probably. Please to be gentle.
145
146 # SEE ALSO
147
148 * http://www.modestmaps.com/
149
150 * http://developer.cloudmade.com/
151
152 * http://raphaeljs.com/
153
154 * http://www.getlatlon.com/
155
156 * http://github.com/straup/js-flickr-api/
157
158 * http://github.com/straup/js-geolocation/