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