view release on metacpan or  search on metacpan

lib/HTML/GMap/Tutorial.pm  view on Meta::CPAN

package HTML::GMap::Tutorial;

our $VERSION = '0.06';

# $Id: Tutorial.pm,v 1.12 2007/07/27 15:38:36 canaran Exp $

use warnings;
use strict;

=head1 NAME

HTML::GMap::Tutorial - HTML::GMap distribution tutorial

=head1 DESCRIPTION

This is the tutorial for HTML::GMap module.

=head1 INTRODUCTION

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.

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...

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...

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 long...

=head1 DESIGN

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 thes...

=head1 INSTALLATION AND COMPONENTS

HTML::GMap package can be installed as any other CPAN module.

The package contains the following modules:

  HTML::GMap           - Core module.
  HTML::GMap::Files    - A container to store HTML and Javascript templates
                         and a CSS file. This file is not intended to be used
                         directly. It is used by HTML::GMap to create temp 
                         copies of these non-Perl files.
  HTML::GMap::Tutorial - Tutorial.

=head1 REQUIREMENTS

=head2 Environment

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.

=head2 Using the Google Maps Service

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 characte...

Google Maps API Sign up Page: <http://www.google.com/apis/maps/signup.html>

=head2 Back-end Database

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 da...

=head2 Web Server (Apache)

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 direc...

=head2 Prototype Javascript Framework

You need the Prototype Javascript Framework, a single file that can be downloaded from its home page at <http://www.prototypejs.org/>.

=head1 DEMO

As described earlier, HTML::GMap can be used to present data in two different modes:

 - High Resolution (hires) mode
 - Pie Chart (piechart) mode

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.

=head2 Displaying Data in hires mode

Let's build the chain store example which we explained in the Introduction section above.