NAME¶
Geo::Google::MapObject - Code to help with managing the server side of the
Google Maps API
VERSION¶
Version 0.06
SYNOPSIS¶
use HTML::Template::Pluggable;
use HTML::Template::Plugin::Dot;
use Geo::Google::MapObject;
my $map = Geo::Google::MapObject->new(
key => 'ABQFbHAATHwok56Qe3MBtg0s7lgkHBS9HKneet7v0OIFhIwnBhTEGCHLTRRRBa_lUOCy1fDamS5PQt8qULYfYQ',
zoom => 13,
size => '512x400',
maptype => 'terrain',
markers=>
[
{
location=>'51.242844,0.011716',
color=>'green',
label=>'P',
title=>'Periapt Technologies',
href=>'http://www.periapt.co.uk'
},
{
location=>'51.243757,0.006051',
color=>'red',
label=>'C',
title=>'Crown Roast Butchers',
href=>'http://www.crownroast.co.uk/'
},
]
);
my $template = HTML::Template::Pluggable->new(file=>'map.tmpl');
$template->param(map=>$map);
return $template->output;
DESCRIPTION¶
This module is intended to provide a server side solution to working with the
Google Maps API. In particular an object of this class encapsulates a
"map" object that provides support for the static maps API, the
javascript maps API, AJAX calls and non-javascript fallback data; but without
making many assumptions about the surrounding framework. We do assume that a
template framework with support for a "dot" notation is being used,
for example HTML::Template::Pluggable. An important commitment of the module
is support for graceful and consistent fallback to a functional non-javascript
web page.
The javascript and static Google map APIs do not behave in quite the same way
when zoom and center are not specified. Specifically it works quite well with
the static maps
(<
http://code.google.com/apis/maps/documentation/staticmaps/#ImplicitPositioning>)
but not so well with the javascript API. To compensate for this the module
gives a choice between: specifying the center and zoom levels; allowing the
APIs and client side code to do whatever they think best; using a built in
algorithm to calculate a sensible zoom and center; and finally supplying ones
own algorithm to calculate a sensible zoom and center.
INTERFACE¶
new¶
Supported arguments are
- autozoom
- If no center and/or zoom is specified this parameter can be
used to calculate suitable values by a process of averaging the markers.
If this parameter is an integer between 0 and 21 then that number is taken
as a maximum zoom level and the builtin algorithm,
"calculate_zoom_and_center", is used with that maximum zoom
level. If the parameter is a CODE ref, then that function is used instead.
The CODE ref must take an ARRAY ref of marker specifications as an input,
and must return a pair consisting of the zoom level as an integer followed
by a latitude-longitude string representing the center. Finally if the
argument is blessed and has a "calculate_zoom_and_center"
method, that will be used. For AUTO calculation of the center or zoom all
the markers must be in the form "decimal,decimal". The
"json" method will delete this as it has no meaning once the
zoom level and center have been determined.
- center
- This must be a location that would be recognized by the
Google maps API. If absent, and if no autozoom has been set, the Google
maps API and client side javascript code must between them work out a
center.
- zoom
- This represents the zoom level
(<http://code.google.com/apis/maps/documentation/staticmaps/#Zoomlevels>),
which is a number between 0 and 21 inclusive. If absent (with no autozoom
set) the API and client will need to set it.
- size
- The size
(<http://code.google.com/apis/maps/documentation/staticmaps/#Imagesizes>)
must either be a string consisting of two numbers joined by the symbol
"x", or a hash ref with width and height parameters. In either
case the first number is the width and the second the height. If absent
the Google API will be allowed to set the size as it sees fit.
- format
- The optional format
(<http://code.google.com/apis/maps/documentation/staticmaps/#ImageFormats>)
must be one of 'png8', 'png', 'png32', 'gif', 'jpg', 'jpg-baseline'. If
absent the Google API will be allowed to set the format as it sees fit.
Note that although the "json" method will pass this on, it seems
to have no meaning in the dynamic API.
- maptype
- This must be one of the following: 'roadmap', 'satellite',
'terrain', 'hybrid's described in
<http://code.google.com/apis/maps/documentation/staticmaps/#MapTypes>.
The "json" method will translate these into numerical codes
roadmap => 0, satellite => 1, terrain => 2 and hybrid => 3 as
this makes it easy for the javascript code
(<http://code.google.com/apis/maps/documentation/reference.html#GMapType.Constants>)
to translate this numerical code into the client side codes. For example:
var mapping = new Array(G_NORMAL_MAP, G_SATELLITE_MAP, G_PHYSICAL_MAP, G_HYBRID_MAP);
var maptype = mapping[data.maptype];
- mobile
- This parameter should be either the string 'true' or
'false' and defaults to 'false'. The static API uses it to provide more
robust tiles as described in
<http://code.google.com/apis/maps/documentation/staticmaps/#Mobile>.
However it seems to have no meaning for the dynamic API.
- key
- The mandatory API key. You can sign up for one at
<http://code.google.com/apis/maps/signup.html>.
- sensor
- This parameter should be either the string 'true' or
'false' and defaults to 'false'. Both versions of the Google API require
it
(<http://code.google.com/apis/maps/documentation/staticmaps/#Sensor>)
and this is reflected in this module by it being used by the
"static_map_url" and "javascript_url" methods.
- markers
- If present the markers should be an array ref of marker
specifications so that it can be used in a TMPL_LOOP. Each marker
specification should be a hash ref and may contain whatever keys are
required by the javascript client side code. It must however have a
"location" field which must be interpretable by the Google API
as a location. In general this means the location must be a string of the
form "decimal,decimal", where the first decimal is the latitude
and the second longitude. Other fields might include for example: id,
title, href, icon. Generally these just get passed through by the
"json" method and should be used by the client side code as it
sees fit. Three fields that have a special meaning, "color",
"size", "label" are those described by the static maps
API
(<http://code.google.com/apis/maps/documentation/staticmaps/#MarkerStyles>).
The GIcon class
(<http://code.google.com/apis/maps/documentation/reference.html#GIcon>)
contains lots of ways of specialising the look and feel of the markers in
the dynamic API; but I can find no easy way of consistently replicating
the the static marker styles in the dynamic API. The only other field
which gets special treatment is "title". The "json"
method will encode the title field. So for example if a marker has a title
field of 'Scloß', then if the javascript code uses this as the
title attribute when creating a GMarker, then hovering the mouse over that
marker will display the German word for castle.
- hl
- This parameter specifies the language to be used. If absent
the API will select the language. Only the dynamic javascript API seems to
use this parameter as described in
<http://code.google.com/apis/maps/documentation/#Localization>. As
such this is used in the "javascript_url" method.
calculate_zoom_and_center¶
This function tales a reference to an array of marker specifications and a
maximum zoom level and returns a pair consisting of a suggested zoom level and
a center.
The algorithm works by iteratively building the following objects:
- A set of points, starting with the first element of the
array and adding the next one at each iteration.
- Actually we don't actually have a variable for this, but
without thinking about this set conceptually I cannot state the algorithm.
The set starts of consisting of just the first marker location.
- "($ctheta, $cphi)"
- These numbers represent a central point of the set of
points represented as radians. The algorithm does not guarantee that the
point is the true centre but we treat it as the centre of a circle. This
starts of by taking the first element and converting its latitude and
longitude to radians.
- $radius
- This variable is initialised to 0.
- The contract
- The algorithm requires that at each iteration all the
points in the set are at most $radius radians from ($ctheta, $cphi).
- The iteration
- We look at the next point. We look at the distance
($distance) between the new point and "($ctheta, $cphi)". If
this is less than or equal to $radius the iteration is over. Otherwise the
following happens:
($ctheta, $cphi) = mid point of ($ctheta, $cphi) and the new point
$radius = $radius + 0.5 * distance between ($ctheta, $cphi) and the new point
- At the end
- We convert "($ctheta, $cphi)" back to latitude
and longitude and logarithmically convert the radius to a zoom level.
I doubt that this algorithm is optimal but it seems quick, uses only one pass
through the markers and can be seen in action at
<
http://testmaps.periapt.co.uk>. Also if you have a better one you can
specify it by passing a suitable CODE ref or blessed scalar to the
"autozoom" parameter of the constructor.
static_map_url¶
Returns a URL suitable for use with the static maps API based upon the arguments
passed to the constructor.
javascript_url¶
Returns a URL suitable for use in loading the dynamic map API.
markers¶
This returns the marker array ref.
json¶
This function uses the JSON module to return a JSON representation of the
object. It removes the API key as that should not be required by any
javascript client side code. If any marker object has a title attribute, then
that attribute is encoded so it will display correctly during mouse overs.
width¶
This returns the width of the image or undef if none has been set.
height¶
This returns the height of the image or undef if none has been set.
TUTORIAL¶
This module only covers the server side of a two way conversation between server
and a talkative client. As such the tutorial must also consider HTML and
javascript. Also to understand this tutorial we assume at least passing
familiarity with the following:
- HTML::Template::Pluggable or some other templating
framework using the "dot" notation.
- The Google maps API:
<http://code.google.com/apis/maps/documentation/reference.html>.
- The static Google maps API:
<http://code.google.com/apis/maps/documentation/staticmaps/>
- Javascript, AJAX. Specifically we are using the yui
framework (<http://developer.yahoo.com/yui/2/>) though any other
framework will do.
The markup¶
We probably have a template file, map.tmpl, some thing like the following:
<html>
<head>
<title>Test Map Tutorial</title>
<!-- This way we tell the javascript what URL to contact the server with. -->
<link href="/map_json" id="get_init_data"/>
<!-- This will be filled in with the correct URL to load the Google maps javascript API. -->
<script type="text/javascript" src="<TMPL_VAR NAME="maps.javascript_url()">"></script>
<!-- This will load the yui API. If you use a different javascript API this would obviously change. -->
<script type="text/javascript" src="http://yui.yahooapis.com/2.8.0r4/build/yahoo-dom-event/yahoo-dom-event.js"></script>
<script type="text/javascript" src="http://yui.yahooapis.com/2.8.0r4/build/connection/connection.js"></script>
<script type="text/javascript" src="http://yui.yahooapis.com/2.8.0r4/build/json/json-min.js"></script>
<!-- This loads our javascript code. -->
<script type="text/javascript" src="/js/maps.js"></script>
</head>
<body>
<!-- This div will be completely replaced by the Google API and is identified by #map_canvas. -->
<div id="map_canvas">
<!-- This image will be loaded by the static Google map API. It will be available whilst the
javascript based map is loading and if javascript is turned off
-->
<div><img
alt="Test map"
src="<TMPL_VAR NAME="maps.static_map_url()">"
width="<TMPL_VAR NAME="maps.width()">"
height="<TMPL_VAR NAME="maps.height()">"
/>
</div>
<!-- The following will be used if javascript is disabled.
We can use it display information that would normally be obtained by
hovering over or clicking on markers on the dynamic map display.
-->
<noscript>
<table>
<TMPL_LOOP NAME="maps.markers()">
<tr>
<td class="google_<TMPL_VAR NAME="this.color">"><TMPL_VAR NAME="this.label"></td>
<td>
<TMPL_IF NAME="this.href">
<a href="<TMPL_VAR NAME="this.href">">
</TMPL_IF>
<TMPL_VAR NAME="this.title">
<TMPL_IF NAME="this.href">
</a>
</TMPL_IF>
</td>
</tr>
</TMPL_LOOP>
</table>
</noscript>
</div> <!-- end of #map_canvas -->
</body>
</html>
The perl¶
The code to actually produce the web page must look something like this:
use HTML::Template::Pluggable;
use HTML::Template::Plugin::Dot;
use Geo::Google::MapObject;
my $t = HTML::Template::Pluggable->new(filename => 'map.tmpl');
my $map = Geo::Google::MapObject->new(....);
$t->param(maps=>$map);
print $t->output;
This is all that would be needed in a javascript free environment. With
javascript enabled the client is going to ask for the same data in a JSON
format (at least we are only supporting JSON). The code to service that
request will look something like:
use Geo::Google::MapObject;
my $map = Geo::Google::MapObject->new(....);
print $map->json;
The javascript¶
As indicated in the markup above we are expecting the javascript to be in a file
called maps.js. We expect it to look something like the following:
function mapInitialize() {
/* Read the "link" element that tells us how to contact the server. See markup above. */
var get_init_data = YAHOO.util.Dom.get('get_init_data').href;
/* Build the AJAX callback object consisting of three parts. */
var callback =
{
/* Part I: Function called in the event of a successful call. */
success: function(o) {
/* Convert the JSON response into a javascript object.
This structure corresponds to the Geo::Google::MapObject in perl
as intermediated by its "json" method.
*/
var data = YAHOO.lang.JSON.parse(o.responseText);
if (GBrowserIsCompatible()) {
/* Build up the Map object which will replace #map_canvas in the above markup. */
var mapopt = {};
if (data.size) {
mapopt.size = new GSize(parseInt(data.size.width), parseInt(data.size.height));
}
var markers = data.markers;
var map = new GMap2(YAHOO.util.Dom.get("map_canvas"), mapopt);
var maptype = null;
if (data.maptype) {
maptype = o.argument[parseInt(data.maptype)];
}
var zoom = null;
if (data.zoom) {
zoom = parseInt(data.zoom);
}
var center = markers[0].location;
if (data.center) {
center = data.center;
}
map.setCenter(GLatLng.fromUrlValue(center), zoom, maptype);
map.setUIToDefault();
/* Now for each marker build and add a GMarker object */
for(var i = 0; i < markers.length; i++) {
var opt = {title: markers[i].title};
if (!markers[i].href) {
opt.clickable = false;
}
if (markers[i].icon) {
opt.icon = new GIcon(G_DEFAULT_ICON, markers[i].icon);
if (markers[i].shadow) {
opt.icon.shadow = markers[i].shadow;
}
}
var mark = new GMarker(GLatLng.fromUrlValue(markers[i].location), opt);
if (markers[i].href) {
mark.href = markers[i].href;
GEvent.addListener(mark, "click", function(){window.location=this.href;});
}
map.addOverlay(mark);
}
}
}, /* End of Part I */
/* Part II: Function called in the event of failure */
failure: function(o) {alert(o.statusText);},
/* Part III: Data that is passed to the success function.
We are using this to map from numerical maptypes that Geo::Google::MapObject has passed us to the
forms used in Google maps API.
*/
argument: [G_NORMAL_MAP, G_SATELLITE_MAP, G_PHYSICAL_MAP, G_HYBRID_MAP]
}; /* End of constructing the AJAX callback object. */
/* This calls the server which should hopefully kick off callback.success with lots of lovely data. */
var transaction = YAHOO.util.Connect.asyncRequest('GET', get_init_data, callback, null);
} /* end of mapInitialize function */
/* This will make sure that we call the above function at a good time. */
YAHOO.util.Event.onDOMReady(mapInitialize);
/* We still have to do the memory cleanup ourselves. */
YAHOO.util.Event.addListener(window, 'unload', 'GUnload');
Taking it further¶
There are lots of variations that can be done with this. The
Geo::Google::MapObject object will pass on all fields it does not recognize
via the "json" function and these can be used by the javascript in
whatever way required. Similarly fields added to the marker specification will
be passed by the "markers" function and can be used in the template
in whatever way required.
You can also make the markers draggable and have the act of dragging a marker
update data on the server. There is an example of where this has been done at
<
http://testmaps.periapt.co.uk>. The details of how this is done depend
intrinsically on the implementation of the data storage on the server. I would
suggest that in general the steps required to make the markers draggable might
be as follows:
- Clean interface to the data storage.
- I think this is a clear case where an ORM
(<http://en.wikipedia.org/wiki/Object-relational_mapping>) offers
some advantages. You could look at DBIx::Class or write your own interface
using DBI.
- Derive a class from Geo::Google::MapObject.
- Your derived class constructor should get the data you need
from the data storage interface layer, use it to create a
Geo::Google::MapObject and bless that into your derived class.
- Provide URLs that update the data underlying your map
objects.
- These will probably be POST methods and need not return
anything other than an "OK" string. They should probably call
the data storage interface layer directly to update the data. There is no
point creating a map object merely to update the underlying data.
- Add link elements to your markup indicating which URL is
needed to update the marker data.
-
<link href="/move_marker" id="move_marker"/>
An advantage of using these link elements is that you might have multiple
maps to manage. By using the link elements to communicate with the client
side, a lot more code and templates can be reused.
- Get the javascript side to read your new link
elements.
-
var move_marker = YAHOO.util.Dom.get('move_marker').href;
- Add a "draggable" flag to the GMarker
constructor
-
var opt = {title: markers[i].title, draggable: true};
- Make sure your GMarkers are labelled in a way that your
server can understand
- Just after the GMarker object, mark, has been created add
mark.label = markers[i].label;
- Make your GMarker object subscribe to the
"dragend" event.
-
GEvent.addListener(mark,
"dragend",
function(latlng) {
var location = latlng.toUrlValue(12);
var postdata = "id="+this.label+"&location="+location;
YAHOO.util.Connect.asyncRequest('POST',
move_marker,
{
success: function(o){},
failure: function(o) {alert(o.statusText);},
argument: []
},
postdata);
});
DIAGNOSTICS¶
- "markers should be an ARRAY"
- The markers parameter of the constructor must be an ARRAY
ref of marker configuration data.
- "no API key"
- To use this module you must sign up for an API key
(http://code.google.com/apis/maps/signup.html) and supply it as the key
parameter.
- "zoom not a number: %s"
- There must be a zoom parameter which is a number from 0 to
21.
- "maptype %s not recognized"
- The maptype must be one of roadmap, satellite, terrain,
hybrid.
- "no width"
- "no height"
- "width should be positive and no more than
640"
- "height should be positive and no more than
640"
- "cannot recognize size"
- The size parameter must either be a string like
"300x500" or a hash array like {width=>300,height=>500}.
And both width and height must be between 1 and 640 inclusive.
- "cannot calculate autozoom without markers"
- If you pass an "autozoom" parameter to the
constructor you must also pass at least one marker.
- "% not recognized as autozoom"
- An autozoom parameter was passed to the constructor that
was not recognized as such.
- "location missing"
- A marker specification was missing a location during
autozoom calculation.
- "no location for %s"
- Every marker object must have a location.
CONFIGURATION AND ENVIRONMENT¶
Geo::Google::MapObject requires no configuration files or environment variables.
DEPENDENCIES¶
- Templating framework
- We assume the use of HTML::Template::Pluggable and
HTML::Template::Plugin though other template frameworks may work.
- Google Maps API
- You need to have one of these which can be obtained from
<http://code.google.com/apis/maps/signup.html>.
- Javascript and AJAX
- We assume a degree of familiarity with javascript, AJAX and
client side programming. For the purposes of documentation we assume YUI:
<http://developer.yahoo.com/yui/>, but this choice of framework is
not mandated.
- Math::Trig
- The autozoom algorithm optionally used by this module
depends upon the Math::Trig for its mathematical calculations. Since
alternative algorithms or no algorithm at all can be used, I think it
might be better to have this as a separate module.
INCOMPATIBILITIES¶
None reported.
BUGS AND LIMITATIONS¶
- paths etc
- Currently there is no support for paths, polygons or
viewports.
- version 3
- We are currently only supporting version 2 of the API.
- testing
- We encode the title attributes of markers in the
"json" function as this seems to be necessary. However I have
not yet managed to get a decent test script for this behaviour. There are
many other cases that should be tested though I think the most critical
cases have been tested.
- character encoding
- This module is only tested against UTF-8 web pages. I have
no intention of changing this as I cannot think of why anyone would
consciously choose to encode web pages in any other way. I am open to
persuasion however.
Please report any bugs or feature requests to
"bug-geo-google-mapobject@rt.cpan.org", or through the web interface
at <
http://rt.cpan.org>.
ACKNOWLEDGEMENTS¶
Thanks to Andreas Koenig for pointing out that this module had an issue with
"Build.PL".
AUTHOR¶
Nicholas Bamber "<nicholas@periapt.co.uk>"
LICENCE AND COPYRIGHT¶
Copyright (c) 2009, Nicholas Bamber "<nicholas@periapt.co.uk>".
All rights reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself. See perlartistic.
DISCLAIMER OF WARRANTY¶
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE
PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR
CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE
SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO
LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER
SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.