HTML-GMap
view release on metacpan or search on metacpan
lib/HTML/GMap/Tutorial.pm view on Meta::CPAN
| pharmacy | char(3) | YES | MUL | NULL | |
| open24 | char(3) | YES | MUL | NULL | |
+-----------+-------------+------+-----+---------+----------------+
id : the primary key
latitude : latitude of store
longitude : longitude of store
name : the name of the store
pharmacy : whether the store has a pharmacy department
open24 : whether the store is open 24-hours
First 10 rows in the table look like this:
mysql> select * from html_gmap_hires_sample limit 10;
+----+------------------+-------------------+-----------+----------+--------+
| id | latitude | longitude | name | pharmacy | open24 |
+----+------------------+-------------------+-----------+----------+--------+
| 1 | 40.9238307736974 | -75.4030897185631 | Store #1 | Yes | Yes |
| 2 | 40.7992166092141 | -75.5955783495462 | Store #2 | No | No |
| 3 | 40.2296733106477 | -74.9588939230624 | Store #3 | No | Yes |
| 4 | 40.6157298274265 | -74.7609734908294 | Store #4 | No | Yes |
| 5 | 40.3437587749323 | -75.6761027474891 | Store #5 | No | Yes |
| 6 | 39.8856390921787 | -72.8002781457194 | Store #6 | Yes | Yes |
| 7 | 40.3589340793951 | -73.8374056778696 | Store #7 | No | Yes |
| 8 | 39.911120200648 | -73.6606559871681 | Store #8 | Yes | No |
| 9 | 41.548534604991 | -74.0078654025807 | Store #9 | Yes | Yes |
| 10 | 41.8260254817441 | -75.3182839751613 | Store #10 | No | Yes |
+----+------------------+-------------------+-----------+----------+--------+
The following script is sufficient to display the data in this table. In its most basic form, you only need to instantiate a HTML::GMap object and call its display method.
#!/usr/bin/perl
use warnings;
use strict;
use HTML::GMap;
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 => ['DBI:mysql:database=temp;host=localhost;port=3306',
'gmap', 'gmap'],
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 => qq[.... <gmap_key> ....],
temp_dir => qq[/usr/local/panzea/html/demo/tmp],
temp_dir_eq => qq[http://localhost:8080/demo/tmp],
);
# Display
$gmap->display;
Let's go through the parameters passed on to the constructor:
I<initial_format>
This parameter defines the mode. It can be one of 'xml-hires' or 'xml-piechart'.
I<page_title, header & footer>
You can customize the pages with your page title, header and footer. "page_title" is the title of the page that is displayed on the title bar of the browser and top of the page. "header" and "footer" contain the HTML content that make up the header a...
I<db_access_params>
The data displayed on the map lives on a MySQL database. "db_access_params" is used to pass on the database access parameters. It is formatted as and array ref containing the datasource, username and password. The datasource is formatted for DBI (ple...
[$password, $username, $password]
I<base_sql_table, base_sql_fields & base_output_headers>
These three parameters describe how the data is stored in the database.
"base_sql_table" describes the name of the table. This can be a clause consisting of JOINs. However, for simplicity and speed, it is recommended to use a single denormalized table. This parameter is passed on as a string (scalar).
Every time the map is moved, a request is made to the server for data corresponding to the location where the map is then placed. The server returns an XML document with the relevant information. "base_sql_fields" describes which fields are returned ...
For each column name passed on by "base_sql_fields", a header is provided by the "base_output_headers" parameter. These headers are used in display. This parameter is passed on as an array ref.
I<legend_field1 & legend_field2>
In hires mode, each data point has two attributes, first of which determines the icon used for the data point on the map and the second one determines the color of the icon used. "legend_field1" and "legend_field2" describe the two columns that are u...
I<param_fields>
This parameter describes the parameter fields that are going to be used as filters. It is passed on as a hash ref.
In this example, first parameter field is "pharmacy". The keys come from base_sql_fields. The value for pharmacy is an array ref which contains the values that will be displayed for the filter parameter as a drop-down list.
pharmacy => ['all:All', 'Yes', 'No']
There are three values 'all:All", 'Yes' and 'No'.
'all:All' describes that the value 'all' will be used. However, when this is displayed on a drop-down list, 'All' is displayed instead of 'all'. This format allows a value in the database to be displayed by a different view on the page. The followin...
It should also be noted that, the value 'all' is a reserved value as a parameter.
I<gmap_key>
This the Google Maps API key described earlier.
I<temp_dir & temp_dir_eq>
HTML::GMap uses a temp directory to store generated icons and other files. This directory needs to be writable by the user which Apache runs as. Also, it needs to be accessible through the web.
"temp_dir" is the full path to the location of the directory. "temp_dir_eq" is the URL-equivalent of this directory.
For example, if the DOCUMENT_ROOT of the web site that will be hosting the view is "/usr/local/demo/html" and temp_dir is "/usr/local/demo/html/demo/tmp", the temp_dir_ew would be "http://<domain_name>/demo/tmp".
After we construct the HTML::GMap object, we can now call the display method:
$gmap->display;
This creates the initial display and handles any subsequent AJAX requests to serve more data.
=head2 Displaying Data in piechart mode
Similar to the previous example, let's build the physician example described in the Introduction section. Please go through the previous section before reading this one as shared features not discussed in this example.
A sample table populated with random data follows:
The table looks like this:
mysql> desc html_gmap_piechart_sample;
+-----------+-------------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+-----------+-------------+------+-----+---------+----------------+
| id | int(11) | NO | PRI | NULL | auto_increment |
| latitude | double | YES | MUL | NULL | |
| longitude | double | YES | MUL | NULL | |
| name | varchar(30) | YES | | NULL | |
| specialty | varchar(30) | YES | MUL | NULL | |
| insurance | char(3) | YES | MUL | NULL | |
+-----------+-------------+------+-----+---------+----------------+
id : the primary key
latitude : latitude of physician
longitude : longitude of physician
name : the name of the physician
specialty : physician's specialty
insurance : whether the physician accepts a particular insurance plan
lib/HTML/GMap/Tutorial.pm view on Meta::CPAN
use HTML::GMap;
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 => ['DBI:mysql:database=temp;host=localhost;port=3306',
'gmap', 'gmap'],
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 => qq[.... <gmap_key> ....],
temp_dir => qq[/usr/local/panzea/html/demo/tmp],
temp_dir_eq => qq[http://localhost:8080/demo/tmp],
);
# Display
$gmap->display;
Let's go through the parameters passed on to the constructor:
I<initial_format>
Same as previous example.
I<page_title, header & footer>
Same as previous example.
I<db_access_params>
Same as previous example.
I<base_sql_table, base_sql_fields & base_output_headers>
Same as previous example. Please see "cluster_field" param below for additional information.
I<cluster_field>
In piechart mode, pie charts are prepared by the count of data points by a single attribute. In this example, the number of physicians with a particular specialty is used to make pie charts. "cluster_field" describes the field which is used to cluste...
"cluster_field" in piechart mode is analogous to "legend_field1" and "legend_field2" in hires mode. This field must be among the fields retrieved by "base_sql_fields".
I<param_fields>
Same as previous example.
I<gmap_key>
Same as previous example.
I<temp_dir & temp_dir_eq>
Same as previous example.
Similar to the previous example, after we construct the HTML::GMap object, we can now call the display method:
$gmap->display;
This creates the initial display and handles any subsequent AJAX requests to serve more data.
=head2 Additional Features & Further Customization
As demonstrate with two examples above, you can build a fully functional display simply by instantiating a HTML::GMap object and then calling its display method.
However, there may be cases in which you might want to create the HTML::GMap object and use the database handle, session id, etc. to calculate some features and pass them back on to the object before calling its display method.
For example, in the piechart example given earlier, the "parameter_fields" parameter is passed on as follows:
param_fields => {
specialty => ['all:All', 'Specialty #1', 'Specialty #2',
'Specialty #3', 'Specialty #4', 'Specialty #5'],
insurance => ['all:All', 'Yes', 'No'],
},
Hardcoding names as such might not be desirable. Instead, you can do the following:
...
my $gmap = HTML::GMap->new (
...
);
my $dbh = $gmap->dbh;
my @specialties = ... # Use dbh to retrieve a "distinct"
set of specialties from the database
$gmap->param_fields({
specialty => \@specialties,
insurance => ['all:All', 'Yes', 'No'],
});
$gmap->display;
In addition to the constructor params demonstrated in the examples, the following params can be used to further customize the display. Please note that all the params can be used as get/set methods as well.
I<page_title, header & footer>
These were demonstrated with the examples. They are not mandatory.
I<messages>
( run in 1.589 second using v1.01-cache-2.11-cpan-5735350b133 )