NAME

WebGUI::Macro::GoogleMaps

DESCRIPTION

The GoogleMaps macro allows you to display a google maps map containing markers at the addresses in an address list. Clicking on the markers opens a templatable popup infoc 'cloud'. Additionally a side bar can be displayed containing the entries, clicking on which pan the maps to the address associated with that entry and opens its info 'cloud'.

The address list can be the users in a WebGUI group or an XML file containing addresses. In the former case addresses are extracted from the users profile. Finally it is possible to display just one marker poniting to an address entered in the parameters of the macro. It is possible to display just one address entered directly in the macros parameters. In that case usage of info clouds and sidebar is disabled.

SEE IT IN ACTION

Live examples plus explantions can be found here: http://www.oqapi.nl/googlemaps-macro

INSTALLATION

Make sure you download the latest version (as of now 1.0.1), put the file in WebGUI/lib/WebGUI/Macro, and rename it to Googlemaps.pm. Enable the macro in your configuration file and don't forget to restart your apache. 

USAGE

Before you can do anything you'll need a Google Maps API Key for your domain. You can obtain one here:

    http://www.google.com/apis/maps/signup.html

Usage examples are shown below:

^GoogleMaps(group=3,showSidebar=1,key=YOURKEYHERE);

^GoogleMaps(xml=http://example.com/addresses.xml,xmlContainer=person,addressComposition=fullAddress;country,nameComposition=name);

^GoogleMaps("address=Rotterdamseweg 183c Delft Nederland",key=YOURKEYHERE);

PARAMETERS

Parameters are passed to the GoogleMaps macro in key=value fashion. See the usage examples if you do not understand what I mean with that. 

NOTE: Either xml, group or address is required and they are mutually exclusive. This means that you can only use one of them. The key is required too, but can also be put in the config file.

xml
    The data source is an xml file. The value should be the url to this file.
    ie. "xml=http://example.com/myAddresses.xml"

group
    The data source is a WebGUI group. The value should be the id of the group.
    ie. "group=3"  (All admins).

address
    The macro displays just one address. The value should be the address.
    ie. "address=Rotterdamse weg 183c Delft Nederland" (Oqapi HQ)

key
    The Google Maps API key for your domain. You can also put this key in your
    webgui configuration file. To do that add an entry called
    "googleMapsApiKey". If you do that you can skip this option.  ie.
    "key=ABQIAAAA6N24ruKdelIxRFPdrXxPBRSbgCKulLifscvmfKz18hFXjKDCzhSBA9LoumpbK2Rw1udOLBKe__MC"

xmlContainer
    The container in which each entry resides. Defaults to 'item'.

addressComposition
    The fieldnames of the fields in your data source that comprise an address
    understandable by the Google geocoder. Seperate fields with a semi colon.
    ie. "addressComposition=street;number;zip;city"

    Defaults to 'homeAddress;homeZip;homeCity;homeState;homeCountry' for a group
    datasources.  Defaults to 'address;zip;city;state;country' for an xml data
    source.

infoBoxTemplate
    The id of the template for the info 'cloud'. Defaults to the default
    template, see below.

showSidebar
    Set this value to 1 in order to show the sidebar. Defaults to no sidebar.

nameComposition
    The composition of names in the sidebar. See addressComposition for syntax.
    Defaults to 'firstName;middleName;lastName'.

width
    The width of the map in pixels. Defaults to 500.

height
    The height of the map in pixels. Defaults to 300.

TEMPLATES

The GoogleMaps macro allows you to template the info 'cloud', and that is probably what you want to do anyway. If you don't, the following templates are used as a default.

For a webgui group data source:
    <b><i><tmpl_var firstName> <tmpl_var middleName> <lastName></i></b><br />
    <tmpl_var homeAddress><br />
    <tmpl_var homeZip> <tmpl_var homeCity>

    The available tmpl_vars are the visible profile fields.

For a xml data source:
    <b><i><tmpl_var name></i></b><br />
    <tmpl_var address><br />
    <tmpl_var zip> <tmpl_var city>

    The avilable tmpl_vars are the xml tags that are in the container.

CAVEATS

This macro does not scale very well with very long lists of addresses. For each address a request is done to the google geocoder, therefore a lot of addresses will cause a long page load. To overcome this problem geocoded addresses are cached. This cache exists for a day and is shared amongst all GoogleMaps macros on your site. If the cache expires you will see a slow pageload again (in case of many addresses). Subsequent page loads should be substantially faster.

Addresses that do not geocode correctly are silently skipped, so if you miss someone check if their address is comprehensible =).

AUTHOR

The GoogleMaps macro copyright 2007 by Martin Kamerbeek

LICENCE

The GoogleMaps macro is licenced GPL v2 and may be distributed under its terms.

The GPL v2 licence can be obtained at http://www.gnu.org/licenses/gpl.html

CHANGELOG

1.0.1

• Fixed a typo that caused the macro to fail for Safari. 

Comments

fathertorque: "it doesn't work with Safari"

martink: "I don't have a mac and thus no access to Safari. Does the regular google maps (maps.google.com) work with Safari 3?
"

fathertorque: "Safari 3 runs on Windows too. You can download it at http://www.apple.com/safari/download

Of course maps.google.com works well with Safari"

martink: "
There was a small typo that caused the generated HTML to be illegal. Firefox and IE apparently ignored that, but Safari didn't. It's fixed in 1.0.1.

 
"

fathertorque: "That's great thank you!
Any chance this can get included into the wG"

martink: "I don't know. If plainblack wants to put it in that's of course fine with me, but it's not up to me to decide whether it'll go in the core."

fathertorque: "Hi martink,
I just installed the macro. I tried with groupid=2 (which should be the users group right?) and only 3 are showned in the map but after a long page load. Does the macro send to google also empty addresses? The server hardware is really fast so that's not a"

martink: "
Sorry for the late reply. I was in France on hollidays. To answer your question; yes it will send google empty addresses. In fact it only caches succeeded geocode lookups so if your group has a lot of empty or invalid addresses pageloads will always take a long time. I've ben planning on chaning the caching mechanism to also cache failed lookups, but didn't have time to do that before I went on vacation.

Server hardware is doesn't really affect the performance of the macro, server bandwidth does.

"

fathertorque: "Another feature request :)
I have two domains for the same website and you can register one key per domain. As of now, if you browse the page with the second domain the map doesn't work. I would like to avoid using mod_rewrite for that... It would be possible for you to add multiple keys support in the code like described here?"

fathertorque: "P.S.
I did a custom cloud template pulling info from profile fields (calling the macro using a webgui group). I would like to include in the cloud the avatar and photo of a user but unfortunately it's not possible as of now it seems... Could it be added in the future?
Also other useful two parameters would be default zoom level and default map view (map, satellite or hybrid).
Templatable sidebar would be also great"

martink: "I'll have to check out why the avatar doesn't work. Default zoom level and map view will be added in a future release. Same goes for the templatable sidebar."

fishingfan: "
Excellent work. 


Chris

CA-Dev.co.uk 
"

martink: "
You'll have to hardcode the keys in your apache conf yourself. However the geocoding is done server side so that still needs a key. I'm not sure which of your keys it needs. Maybe both work, but I don't know that.

Currently the approach in the link you pasted is not possible, because the url of the googlemaps javascript file is generated from within. I'll have to think about adding an option to override that.
"

fathertorque: "
Yes I need both keys to work because if people access the map page on domain B, a popup message from Google appears saying there is no valid key for this domain.

I hope you'll add this asap.  
"

fishingfan: "
Is there a way of controlling the zoom level on the map ?

Also it would be nice to be able to specify hybrid/map/satelite.

I guess the answer would be to hack around with the javascript inside the code ? 

 

Chris

CA-Dev.co.uk 
"

martink: "
These things are currently not possible with the macro, but I certainly want to add them some day. There are other things I want too, but the biggest issue is finding time to do that. Maybe I'll work on these things at the hackathon at the WUC.

Maybe you could use javascript to change these things, maybe not. I don't know that by heart for sure, so you'll have to try it out. Also, from what I've heard on IRC there's a google maps wobject in the making by (I believe) nuba, so you might consider asking him about that.

As a side note, a big problem with adding more and more options to this macro is
that it gets more and more complex to configure. It is very complex
already. So in order to keep it from defying its purpous I am a bit
reluctant to add every odd feature. Zoomlevel and map type however seem
like basic things that should be added. The edit interface of assets would nullify this problem.
"

fishingfan: "
Thanks for the info.  I'll take a look at the javascript and customize to my requirements if necessary, I think you're right that more options are probably more suited to an asset.

I think the killer thing with you macro is the XML list, that is very useful.  Thanks again. 

Chris

CA-Dev.co.uk 
"

doniman: "
Did you manage to set the zoom level? If so I would greatly appreciate knowing how you did it.

Gavin 
"

xootom: "
I've got this working great for a single address, but I'd like to dynamically load a set of addresses using XML. Really, I need to generate the XML using an SQL Report and template. Is there an example XML file showing the required structure?

Also the link to the website containing demos and examples doesn't work any more. 
"

martink: "
Sorry for the late reply, times have been a bit busy and I forgot about your post.

In short you can use almost any xml structure you like as long address data is grouped in one container tag per address. Define your xml structure using the xmlContainer, addressComposition and nameComposition parameters. This is shown and explained in the online examples here. The link to the examples has been fixed as well. Thanks for pointing that out.

Martin
"

xdanger: "The Macro fails if your xml only has one entry.
to fix this:
@@ -185,6 +185,7 @@
    my $data = XMLin($xml,
        KeyAttr         => '',
        SuppressEmpty   => 1,
+        ForceArray      => [$container],
    );

    return $data->{$container};"

xdanger: "I have found that if you have utf-8 in yout addresses the lookup fails.

this helped me:

@@ -5,6 +5,7 @@
use XML::Simple;
use WebGUI::Cache;
use Data::Dumper;
+use Encode;

=head1 NAME

@@ -197,11 +198,14 @@
    my $address = shift;
    my $key = shift;

+    Encode::from_to($address, "utf-8", "iso-8859-15");
    my $uri = URI->new("http://maps.google.com/maps/geo");
    $uri->query_form(q => $address, output => 'csv', key => $key);"