forked from straup/js-iamheremap
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
308 lines (197 loc) · 8.7 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
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/>