/ 
CGI_Imagemap-1.00
River stage zero No dependents
/ CGI::Imagemap

NAME

CGI::Imagemap.pm - imagemap behavior for CGI programs

SYNOPSIS

 use CGI::Imagemap;

 $map = new CGI::Imagemap;
 $map->setmap(@map);
 $action = $map->action($x,$y);

-- or --

use CGI::Imagemap 'action_map';

$action = action_map($x,$y,@map);

DESCRIPTION

CGI::Imagemap allows CGI programmers to place TYPE=IMAGE form fields on their HTML fill-out forms, with either client-side or server-side maps emulated.

The imagemap file follows that of the NCSA imagemap program. Each point is an x,y tuple. Each line in the map consists of one of the following formats. Comment lines start with "#".

circle action center edgepoint
rect action upperleft lowerright
point action point
poly action point1 point2 ... pointN
default action

Using "point" and "default" in the same map makes no sense. If "point" is used, the action for the closest one is selected.

To use CGI::Imagemap, define an image submit map on your form with something like:

<input type=image name=mv_todo
     SRC="image_url">

You can pass a "client-side" imagemap like this:

<input type="hidden" name="todo.map"
		value="rect action1 0,0 25,20">
<input type="hidden" name="todo.map"
		value="rect action2 26,0 50,20">
<input type="hidden" name="todo.map"
		value="rect action3 51,0 75,20">
<input type="hidden" name="todo.map"
		value="default action0">

If the @map passed parameter contains a NUL (\0) in the first array position, the map is assumed to be null-separated and @map is built by splitting it. This allows a null-separated todo.map with multiple values (parsed by a cgi-lib.pl or the like) to be referenced.

All of the following examples assume the above definitions in your form.

Static Methods

CGI::Imagemap allows the export of two routines, action_map and map_untaint. If you choose to use CGI::Imagemap statically, call the module with:

use CGI::Imagemap qw(action_map map_untaint);
action_map(x,y,map)

We are assuming the map definition above, with the type=image variable named todo, and the map in todo.map. You can pass the map in one of two ways. The first is compatible with the CGI.pm (or CGI::*) modules, and passes the map as an array:

$query = new CGI;
my $x = $query->param('todo.x');
my $y = $query->param('todo.y');
my $map = $query->param('todo.map');
$action = action_map($x, $y, $map);

If you are using the old cgi-lib.pl library, which places multiple instances of the same form variable in a scalar, separated by null (\0) characters, you can do this:

ReadParse(*FORM);
my $x = $FORM{'todo.x'};
my $y = $FORM{'todo.y'};
my $map = $FORM{'todo.map'};
$action = action_map($x, $y, $map);
map_untaint($untaint)

If you are running with taint checking, as is suggested for CGI programs, you can use map_untaint(1) to set map untainting on a global basis. (If using class methods, each has its own instance of untainting).

It ensures all characters in the action fit pattern of [-\w.+@]+, meaning alphnumerics, underscores, dashes (-), periods, and the @ sign. It also checks the methods (rect,poly,point,default,circle) and ensures that points/tuples are only integers. Once that is done, it untaints the passed form variables.

map_untaint(1);    # Turns on untainting
map_untaint('yes');# Same as above

map_untaint(0);    # Disable untainting
map_untaint('no'); # Same as above
  
$status = map_untaint(); # Get status

Default is no untainting.

Class Methods

The class methods for CGI::Imagemap are much the same as above, with the exception that multiple imagemaps are then maintained by the module, with full independence. The following method definitions assume the CGI::Form module is being used, like this:

use CGI::Form;
use CGI::Imagemap;

$query  = new CGI::Form;
$map    = new CGI::Imagemap;
setmap(@map)

This sets the map for the instance.

$map = new CGI::Imagemap;
$map->setmap($query->param('todo.map'));
addmap(@map)

This adds a new map action specification to the current map.

$map->addmap('point action5 3,9'));
action(x,y)

This finds the action, based on the active map and the values of x and y,

$x = $query->param('todo.x');
$y = $query->param('todo.y');
$action = $map->action($x, $y);
untaint()

Sets, unsets, or returns the taint status for the instance.

$map->untaint(1);       # Turns on untainting
$map->untaint('yes');   # Same as above
$map->untaint(1);       # Disables untainting
$map->untaint('yes');   # Same as above
$status = $map->untaint(); # Get status
version()

Returns the version number of the module.

EXAMPLE

A couple of self-contained examples are included in the CGI::Imagemap package. They are:

testmap     -  Uses the CGI::Form module
testmap.old -  Uses the old cgi-lib.pl

BUGS

The untainting stuff is not totally independent -- threading might not work very well. This can be fixed if it is important -- in the CGI world, I doubt it.

AUTHOR

Mike Heins, Internet Robotics, <mikeh@iac.net>

CREDITS

This work is heavily kited from the Perl imagemap program originally written by V. Khera <khera@kciLink.com>.