GMap/Tutorial.pm

filter: Statementstmt 100% 8 / 8 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 2 / 2 Podpod n/a totaltotal 100% 10 / 10 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« GMap.pm ↑ Summary
1 package HTML::GMap::Tutorial;
2  
3 1 our $VERSION = '0.06';
4  
5 # $Id: Tutorial.pm,v 1.12 2007/07/27 15:38:36 canaran Exp $
6  
7 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 =head1 NAME
11  
12 HTML::GMap::Tutorial - HTML::GMap distribution tutorial
13  
14 =head1 DESCRIPTION
15  
16 This is the tutorial for HTML::GMap module.
17  
18 =head1 INTRODUCTION
19  
20 Google Maps service provides an AJAX-based geographic map and a Javascript API that allows operations such as overlaying images and lines on the geographic map. The map can be dragged using the mouse.
21  
22 HTML::GMap wraps around the Google Maps API and provides a generic Perl infrastructure that can be used to easily build interactive web applications that display geographic data stored in a database. HTML::GMap handles HTML page rendering, graph/icon generation, Javascript components and interaction with the underlying database.
23  
24 For example, let's say that you have a database that contains locations of stores that belong to a grocery store chain. Each row in your database contains the name of the store, its geographic location (a latitude and a longitude) and some additional properties of each store such as whether the store has a pharmacy department and whether the store is open 24-hours. Using HTML::GMap you can easily set up a page which displays the stores on a geographic map. You can display stores that have a pharmacy store as a square icon and ones that do not as a triangle icon. You can display stores that are open 24-hours with orange icons and ones which are not as blue icons. Up to two properties can be used in this manner. Using HTML::GMap you can set up filters on the side of the view. The user can select from a drop-down list, the stores that are open 24-hours and click filter to display only the ones that match the criteria.
25  
26 HTML::GMap can be used to view data cumulatively using pie charts as well. For example, let's say that you have a database of physicians. Each row in your database contains the name of the physician, his/her geographic location (a latitude and a longitude) and some additional properties such as physicians specialty and whether he/she accepts a particular insurance plan. Using HTML::GMap you can display this information easily on a geographic map. The map is divided into a 10x10 grid based on equal latitudes and longitudes. For each tile, a pie chart is generated on-the-fly with each move of the map and distribution of physician specialties for each tile is displayed. Since map can be zoomed in and out, the tiles can be made larger and smaller. A filter is displayed on the side so that only a single specialty or whether a physician accepts the insurance plan can be selected for views.
27  
28 =head1 DESIGN
29  
30 The setup described above require two types of server-side functionality. The first one generates the initial HTML page. A second functionality is needed to respond to client requests initiated by dragging the map. The HTML::GMap module combines these two functionalities in a single package allowing a simple integrated structure. For more complex applications, the module supports the second functionality to be provided by external sources.
31  
32 =head1 INSTALLATION AND COMPONENTS
33  
34 HTML::GMap package can be installed as any other CPAN module.
35  
36 The package contains the following modules:
37  
38 HTML::GMap - Core module.
39 HTML::GMap::Files - A container to store HTML and Javascript templates
40 and a CSS file. This file is not intended to be used
41 directly. It is used by HTML::GMap to create temp
42 copies of these non-Perl files.
43 HTML::GMap::Tutorial - Tutorial.
44  
45 =head1 REQUIREMENTS
46  
47 =head2 Environment
48  
49 This code was developed for a Linux environment, running Apache as the web server and MySQL as the back-end database server. Running in other compatible environments may require modifications.
50  
51 =head2 Using the Google Maps Service
52  
53 In order to use Google Maps on your website, you need to sign up for the Google Maps API and create an API key. Please refer to Google's Terms & Conditions to determine the service's suitability for your site. The API key is a long string of characters that is specific for your site. Save this key as you will later need to place it in the configuration file.
54  
55 Google Maps API Sign up Page: <http://www.google.com/apis/maps/signup.html>
56  
57 =head2 Back-end Database
58  
59 The display requires a back-end MySQL table that contains the data and the geographic coordinates. For each data point (a row) a "latitude" and a "longitude" column is required. Additional columns are needed to associate more information with each data point.
60  
61 =head2 Web Server (Apache)
62  
63 When you write your Perl script that uses HTML::GMap, you will need to place it in a CGI-executable directory in your web server. In addition to this, you will need a directory which is writable by the user that your web server runs under. This directory will be used to store temp files (mostly icon images). This directory needs to be able to be accessible through the web.
64  
65 =head2 Prototype Javascript Framework
66  
67 You need the Prototype Javascript Framework, a single file that can be downloaded from its home page at <http://www.prototypejs.org/>.
68  
69 =head1 DEMO
70  
71 As described earlier, HTML::GMap can be used to present data in two different modes:
72  
73 - High Resolution (hires) mode
74 - Pie Chart (piechart) mode
75  
76 The following two examples demonstrate these two modes. Please read both examples as many features apply to both modes. These will be introduced in the first example and referenced back by the second example.
77  
78 =head2 Displaying Data in hires mode
79  
80 Let's build the chain store example which we explained in the Introduction section above.
81  
82 We will need a table that contains the data. Here's a sample table populated with random data.
83  
84 The table looks like this:
85  
86 mysql> desc html_gmap_hires_sample;
87 +-----------+-------------+------+-----+---------+----------------+
88 | Field | Type | Null | Key | Default | Extra |
89 +-----------+-------------+------+-----+---------+----------------+
90 | id | int(11) | NO | PRI | NULL | auto_increment |
91 | latitude | double | YES | MUL | NULL | |
92 | longitude | double | YES | MUL | NULL | |
93 | name | varchar(30) | YES | | NULL | |
94 | pharmacy | char(3) | YES | MUL | NULL | |
95 | open24 | char(3) | YES | MUL | NULL | |
96 +-----------+-------------+------+-----+---------+----------------+
97  
98 id : the primary key
99 latitude : latitude of store
100 longitude : longitude of store
101 name : the name of the store
102 pharmacy : whether the store has a pharmacy department
103 open24 : whether the store is open 24-hours
104  
105 First 10 rows in the table look like this:
106  
107 mysql> select * from html_gmap_hires_sample limit 10;
108 +----+------------------+-------------------+-----------+----------+--------+
109 | id | latitude | longitude | name | pharmacy | open24 |
110 +----+------------------+-------------------+-----------+----------+--------+
111 | 1 | 40.9238307736974 | -75.4030897185631 | Store #1 | Yes | Yes |
112 | 2 | 40.7992166092141 | -75.5955783495462 | Store #2 | No | No |
113 | 3 | 40.2296733106477 | -74.9588939230624 | Store #3 | No | Yes |
114 | 4 | 40.6157298274265 | -74.7609734908294 | Store #4 | No | Yes |
115 | 5 | 40.3437587749323 | -75.6761027474891 | Store #5 | No | Yes |
116 | 6 | 39.8856390921787 | -72.8002781457194 | Store #6 | Yes | Yes |
117 | 7 | 40.3589340793951 | -73.8374056778696 | Store #7 | No | Yes |
118 | 8 | 39.911120200648 | -73.6606559871681 | Store #8 | Yes | No |
119 | 9 | 41.548534604991 | -74.0078654025807 | Store #9 | Yes | Yes |
120 | 10 | 41.8260254817441 | -75.3182839751613 | Store #10 | No | Yes |
121 +----+------------------+-------------------+-----------+----------+--------+
122  
123 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.
124  
125 #!/usr/bin/perl
126  
127 use warnings;
128 use strict;
129  
130 use HTML::GMap;
131  
132 my $gmap = HTML::GMap->new (
133 initial_format => 'xml-hires',
134 page_title => 'HTML::GMap hires View Demo',
135 header => '[Placeholder for Header]',
136 footer => '[Placeholder for Header]',
137 db_access_params => ['DBI:mysql:database=temp;host=localhost;port=3306',
138 'gmap', 'gmap'],
139 base_sql_table => qq[html_gmap_hires_sample],
140 base_sql_fields => ['id',
141 'latitude',
142 'longitude',
143 'name',
144 'pharmacy',
145 'open24',
146 ],
147 base_output_headers => ['Id',
148 'Latitude',
149 'Longitude',
150 'Store Name',
151 'Pharmacy',
152 'Open 24 Hours',
153 ],
154 legend_field1 => 'pharmacy',
155 legend_field2 => 'open24',
156 param_fields => {
157 pharmacy => ['all:All', 'Yes', 'No'],
158 open24 => ['all:All', 'Yes', 'No'],
159 },
160 gmap_key => qq[.... <gmap_key> ....],
161 temp_dir => qq[/usr/local/panzea/html/demo/tmp],
162 temp_dir_eq => qq[http://localhost:8080/demo/tmp],
163 );
164  
165 # Display
166 $gmap->display;
167  
168 Let's go through the parameters passed on to the constructor:
169  
170 I<initial_format>
171  
172 This parameter defines the mode. It can be one of 'xml-hires' or 'xml-piechart'.
173  
174 I<page_title, header & footer>
175  
176 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 and footer.
177  
178 I<db_access_params>
179  
180 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 (please refer to DBI documentation if you need details on the format).
181  
182 [$password, $username, $password]
183  
184 I<base_sql_table, base_sql_fields & base_output_headers>
185  
186 These three parameters describe how the data is stored in the database.
187  
188 "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).
189  
190 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 data point. The primary key ("id"), "latitude", "longitude" fields are mandatory. In addition, "name", "pharmacy" and "open24" fields are returned. Please note that "pharmacy" and "open24" fields are the fields that are used in the filter. This parameter is passed on as an array ref.
191  
192 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.
193  
194 I<legend_field1 & legend_field2>
195  
196 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 used for this purpose. These fields are passed on as scalars.
197  
198 I<param_fields>
199  
200 This parameter describes the parameter fields that are going to be used as filters. It is passed on as a hash ref.
201  
202 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.
203  
204 pharmacy => ['all:All', 'Yes', 'No']
205  
206 There are three values 'all:All", 'Yes' and 'No'.
207  
208 '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 following parameters, 'Yes' and 'No" do not have an alternate view, they are displayed as they are.
209  
210 It should also be noted that, the value 'all' is a reserved value as a parameter.
211  
212 I<gmap_key>
213  
214 This the Google Maps API key described earlier.
215  
216 I<temp_dir & temp_dir_eq>
217  
218 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.
219  
220 "temp_dir" is the full path to the location of the directory. "temp_dir_eq" is the URL-equivalent of this directory.
221  
222 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".
223  
224 After we construct the HTML::GMap object, we can now call the display method:
225  
226 $gmap->display;
227  
228 This creates the initial display and handles any subsequent AJAX requests to serve more data.
229  
230 =head2 Displaying Data in piechart mode
231  
232 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.
233  
234 A sample table populated with random data follows:
235  
236 The table looks like this:
237  
238 mysql> desc html_gmap_piechart_sample;
239 +-----------+-------------+------+-----+---------+----------------+
240 | Field | Type | Null | Key | Default | Extra |
241 +-----------+-------------+------+-----+---------+----------------+
242 | id | int(11) | NO | PRI | NULL | auto_increment |
243 | latitude | double | YES | MUL | NULL | |
244 | longitude | double | YES | MUL | NULL | |
245 | name | varchar(30) | YES | | NULL | |
246 | specialty | varchar(30) | YES | MUL | NULL | |
247 | insurance | char(3) | YES | MUL | NULL | |
248 +-----------+-------------+------+-----+---------+----------------+
249  
250 id : the primary key
251 latitude : latitude of physician
252 longitude : longitude of physician
253 name : the name of the physician
254 specialty : physician's specialty
255 insurance : whether the physician accepts a particular insurance plan
256  
257 First 10 rows in the table look like this:
258  
259 mysql> select * from html_gmap_piechart_sample limit 10;
260 +----+------------------+-------------------+---------------+--------------+-----------+
261 | id | latitude | longitude | name | specialty | insurance |
262 +----+------------------+-------------------+---------------+--------------+-----------+
263 | 1 | 40.4884296913242 | -77.1003155108648 | Physician #1 | Specialty #3 | No |
264 | 2 | 41.8454302160773 | -75.16482267814 | Physician #2 | Specialty #5 | No |
265 | 3 | 41.2721700896335 | -78.622291319768 | Physician #3 | Specialty #1 | No |
266 | 4 | 41.4016346345324 | -78.0504781535355 | Physician #4 | Specialty #3 | Yes |
267 | 5 | 41.513092057257 | -76.3753730044735 | Physician #5 | Specialty #3 | Yes |
268 | 6 | 41.3368285220529 | -76.8610737601246 | Physician #6 | Specialty #1 | No |
269 | 7 | 40.6684951710926 | -78.8420805090634 | Physician #7 | Specialty #4 | Yes |
270 | 8 | 41.064080827709 | -77.789377537904 | Physician #8 | Specialty #2 | Yes |
271 | 9 | 40.151821055458 | -75.0997523063612 | Physician #9 | Specialty #5 | No |
272 | 10 | 41.6288865333676 | -77.8815743236442 | Physician #10 | Specialty #5 | Yes |
273 +----+------------------+-------------------+---------------+--------------+-----------+
274  
275 Similar to the previous example, the following script is sufficient to display the data in this table.
276  
277 #!/usr/bin/perl
278  
279 use warnings;
280 use strict;
281  
282 use HTML::GMap;
283  
284 my $gmap = HTML::GMap->new (
285 initial_format => 'xml-piechart',
286 page_title => 'HTML::GMap piechart View Demo',
287 header => '[Placeholder for Header]',
288 footer => '[Placeholder for Header]',
289 db_access_params => ['DBI:mysql:database=temp;host=localhost;port=3306',
290 'gmap', 'gmap'],
291 base_sql_table => qq[html_gmap_piechart_sample],
292 base_sql_fields => ['id',
293 'latitude',
294 'longitude',
295 'name',
296 'specialty',
297 'insurance',
298 ],
299 base_output_headers => ['Id',
300 'Latitude',
301 'Longitude',
302 'Name',
303 'Specialty',
304 'Insurance',
305 ],
306 cluster_field => 'specialty',
307 param_fields => {
308 specialty => ['all:All', 'Specialty #1', 'Specialty #2',
309 'Specialty #3', 'Specialty #4', 'Specialty #5'],
310 insurance => ['all:All', 'Yes', 'No'],
311 },
312 gmap_key => qq[.... <gmap_key> ....],
313 temp_dir => qq[/usr/local/panzea/html/demo/tmp],
314 temp_dir_eq => qq[http://localhost:8080/demo/tmp],
315 );
316  
317 # Display
318 $gmap->display;
319  
320 Let's go through the parameters passed on to the constructor:
321  
322 I<initial_format>
323  
324 Same as previous example.
325  
326 I<page_title, header & footer>
327  
328 Same as previous example.
329  
330 I<db_access_params>
331  
332 Same as previous example.
333  
334 I<base_sql_table, base_sql_fields & base_output_headers>
335  
336 Same as previous example. Please see "cluster_field" param below for additional information.
337  
338 I<cluster_field>
339  
340 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 cluster the data.
341  
342 "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".
343  
344 I<param_fields>
345  
346 Same as previous example.
347  
348 I<gmap_key>
349  
350 Same as previous example.
351  
352 I<temp_dir & temp_dir_eq>
353  
354 Same as previous example.
355  
356 Similar to the previous example, after we construct the HTML::GMap object, we can now call the display method:
357  
358 $gmap->display;
359  
360 This creates the initial display and handles any subsequent AJAX requests to serve more data.
361  
362 =head2 Additional Features & Further Customization
363  
364 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.
365  
366 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.
367  
368 For example, in the piechart example given earlier, the "parameter_fields" parameter is passed on as follows:
369  
370 param_fields => {
371 specialty => ['all:All', 'Specialty #1', 'Specialty #2',
372 'Specialty #3', 'Specialty #4', 'Specialty #5'],
373 insurance => ['all:All', 'Yes', 'No'],
374 },
375  
376 Hardcoding names as such might not be desirable. Instead, you can do the following:
377  
378 ...
379  
380 my $gmap = HTML::GMap->new (
381 ...
382 );
383  
384 my $dbh = $gmap->dbh;
385  
386 my @specialties = ... # Use dbh to retrieve a "distinct"
387 set of specialties from the database
388  
389 $gmap->param_fields({
390 specialty => \@specialties,
391 insurance => ['all:All', 'Yes', 'No'],
392 });
393  
394 $gmap->display;
395  
396 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.
397  
398 I<page_title, header & footer>
399  
400 These were demonstrated with the examples. They are not mandatory.
401  
402 I<messages>
403  
404 This attribute can be set to display a message in the lower right hand corner of the display.
405  
406 I<center_latitude & center_longitude>
407  
408 These parameters can be set to the geographic coordinate that map should pan to when first loaded. If not specified, map pans to default coordinates.
409  
410 I<max_hires_display>
411  
412 In hires mode, when there are more than "max_hires_display" points in display, a lower resolution view of the data points is displayed. The view switches to higher resolution as map is zoomed in. If not specified, this attribute defaults to 100.
413  
414 I<install_dir & install_dir_eq>
415  
416 These parameters define installation directory and its equivalent. Currently its only purpose is to store the prototype.js file. If not specified, defaults to temp-dir and temp_dir_eq respectively.
417  
418 I<image_height_pix & image_width_pix>
419  
420 Height and width of map in pixels. Defaults to 600. *** Currently, alternate values are not tested. ***
421  
422 I<tile_height_pix & tile_width_pix>
423  
424 Height and width of tiles in pixels. Defaults to 60. *** Currently, alternate values are not tested. ***
425  
426 =head1 REMARKS
427  
428 Please refer to HTML::GMap for a list of all attributes and methods and sub-classing information.
429  
430 =head1 TO-DO
431  
432 - Test additional image/tile dimensions.
433 - Implement color/shape persistence in hires mode.
434 - Test and add docs for sub-classing.
435  
436 =head1 AUTHOR
437  
438 Payan Canaran <pcanaran@cpan.org>
439  
440 =head1 BUGS
441  
442 Please report them.
443  
444 =head1 VERSION
445  
446 Version 0.06
447  
448 =head1 ACKNOWLEDGEMENTS
449  
450 =head1 COPYRIGHT & LICENSE
451  
452 Copyright (c) 2006-2007 Cold Spring Harbor Laboratory
453  
454 This program is free software; you can redistribute it and/or modify it
455 under the same terms as Perl itself. See DISCLAIMER.txt for
456 disclaimers of warranty.
457  
458 =cut
459  
460 1 1;
« GMap.pm ↑ Summary