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.

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.

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.

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.

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&szlig;', 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.

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.

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

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.

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.

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:

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>

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:

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:

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.

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.

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.

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.

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.

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.