NAME
HTML::GMap - Generic Perl infrastructure to build Google Maps displays
SYNOPSIS
# hires mode
my
$gmap
= HTML::GMap->new (
initial_format
=>
'xml-hires'
,
page_title
=>
'HTML::GMap hires View Demo'
,
header
=>
'[Placeholder for Header]'
,
footer
=>
'[Placeholder for Header]'
,
db_access_params
=> [
$datasource
,
$username
,
$password
],
base_sql_table
=>
qq[html_gmap_hires_sample]
,
base_sql_fields
=> [
'id'
,
'latitude'
,
'longitude'
,
'name'
,
'pharmacy'
,
'open24'
,
],
base_output_headers
=> [
'Id'
,
'Latitude'
,
'Longitude'
,
'Store Name'
,
'Pharmacy'
,
'Open 24 Hours'
,
],
legend_field1
=>
'pharmacy'
,
legend_field2
=>
'open24'
,
param_fields
=> {
pharmacy
=> [
'all:All'
,
'Yes'
,
'No'
],
open24
=> [
'all:All'
,
'Yes'
,
'No'
],
},
gmap_key
=>
$gmap_key
,
temp_dir
=>
qq[/usr/local/demo/html/demo/tmp]
,
);
$gmap
->display;
# piechart mode
my
$gmap
= HTML::GMap->new (
initial_format
=>
'xml-piechart'
,
page_title
=>
'HTML::GMap piechart View Demo'
,
header
=>
'[Placeholder for Header]'
,
footer
=>
'[Placeholder for Header]'
,
db_access_params
=> [
$datasource
,
$username
,
$password
],
base_sql_table
=>
qq[html_gmap_piechart_sample]
,
base_sql_fields
=> [
'id'
,
'latitude'
,
'longitude'
,
'name'
,
'specialty'
,
'insurance'
,
],
base_output_headers
=> [
'Id'
,
'Latitude'
,
'Longitude'
,
'Name'
,
'Specialty'
,
'Insurance'
,
],
cluster_field
=>
'specialty'
,
param_fields
=> {
specialty
=> [
'all:All'
,
'Specialty #1'
,
'Specialty #2'
,
'Specialty #3'
,
'Specialty #4'
,
'Specialty #5'
],
insurance
=> [
'all:All'
,
'Yes'
,
'No'
],
},
gmap_key
=>
$gmap_key
,
temp_dir
=>
qq[/usr/local/demo/html/demo/tmp]
,
);
$gmap
->display;
DESCRIPTION
This module provides an easy-to-use way to build interactive web-based geographical maps that utilize the Google Maps API.
USAGE
Please refer to HTML::GMap::Tutorial for a tutorial on using HTML::GMap.
QUICK REFERENCE
All the parameters listed below have a get/set method. However, the set functionality of the params in the 3rd group is not intended to be utilized except for development.
Group 1 - Parameters required by the constructor
The following parameters are required by the constructor.
Parameter Description Format
--------- ----------- ------
initial_format Initial display
format
(xml-piechart|xml-hires)
scalar
db_access_params Database access params arrayref
([datasource, username, password])
base_sql_table Base SQL table (or table
join
) to build final
scalar
SQL queries from
base_sql_fields Fields that will be retrieved by the arrayref
SQL statement
base_output_headers Headers that will be output in results arrayref
legend_field1 For hires display, first field to fold on
scalar
(Required only
for
xml-hires)
legend_field2 For hires display, second field to fold on
scalar
(Required only
for
xml-hires)
cluster_field For pie chart display, the field to fold on
scalar
(Required only
for
xml-piechart)
param_fields Param fields to include as filters arrayref
gmap_key Google Maps API key
scalar
temp_dir Temporary directory to store images
scalar
and session files
temp_dir_eq URL-equivalent to access files in temp_dir
scalar
Group 2 - Optional parameters
The following parameters are optional.
Parameter Description Format Default
--------- ----------- ------ -------
page_title Page title
scalar
'Geographical
Display'
header HTML header in views
scalar
''
footer HTML footer in views
scalar
''
messages Initial content to display
scalar
''
in the
"Messages"
section
request_url_template URL template
for
making AJAX
scalar
*set
requests to refresh displays automatically*
center_latitude The initial latitude that the
scalar
40.863233
map
will centered
center_longitude The initial latitude that the
scalar
-73.466566
map
will centered at
max_hires_display For hires display, max number
scalar
100
of data points displayed
when
in high resolution mode
install_dir Directory containing the HTML
scalar
temp_dir
components of installation
install_dir_eq HTML-equivalent to access
scalar
temp_dir_eq
files in install_dir
image_height_pix Height of
map
in pixels
scalar
600
image_width_pix Width of
map
in pixels
scalar
600
tile_height_pix Height of tiles in pixels
scalar
60
tile_width_pix Width of tiles in pixels
scalar
60
Group 3 - Internal methods
The following parameters are set automatically but they can be get/set after object instantiation.
Parameter Description Format
--------- ----------- ------
cgi CGI object CGI
ref
cgi_params CGI params hashref
db_display Display name
for
the database
scalar
in effect
dbh Database handle DBI
ref
db_selected Database specified using the
scalar
database param in the URL
fields Processed form of fields hashref
session CGI::Session object CGI::Session
ref
session_id CGI::Session object id
scalar
OTHER
"db_access_params" can be specified in two forms:
The following format is used when there is only one database that the page will be running on.
db_access_params
=> [
$datasource
,
$username
,
$password
];
Alternatively, a set of databases can be specified and can be addressed by "database=<alias>" URL parameter.
db_access_params
=> [
{
alias
=>
$alias
,
datasource
=>
$datasource2
,
username
=>
$username2
,
password
=>
$password2
,
},
{
alias
=>
$alias
,
datasource
=>
$datasource2
,
username
=>
$username2
,
password
=>
$password2
,
},
];
AUTHOR
Payan Canaran <canaran@cshl.edu>
BUGS
VERSION
Version 0.02
ACKNOWLEDGEMENTS
This module has been initially written for implementing a geographic viewer for displaying maize genetic polymorphism data on Panzea (www.panzea.org), the public web site of the "Molecular and Functional Diversity of the Maize Genome" project. Thanks to project members for their feedback on user features. Particularly thanks to Jeff Glaubitz for his feedback and providing use cases and help in testing the Panzea viewer.
COPYRIGHT & LICENSE
Copyright (c) 2006-2007 Cold Spring Harbor Laboratory
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.