NAME

CGI::Imagemap - interpret NCSA imagemaps for CGI programs

SYNOPSIS

  use CGI::Imagemap;
 
  $map = new CGI::Imagemap;

  $map->addmap(-file=>"image.map");
  #OR
  $map->addmap(@map);

  eval { $action = $map->action($x,$y) };
  #Check $@ for errors

DESCRIPTION

CGI::Imagemap allows CGI programmers to emulate the NCSA imagemap CGI or place TYPE=IMAGE form fields on their forms.

The imagemap file follows that of the NCSA imagemap program. See "NOTES" for further details.

addmap(-file=>image.map)

This appends the contents of the file to the map object.

  $map->addmap('path/to/file.map');

addmap(@map)

This appends @map to the map object.

  $map->addmap('point http://cpan.org 3,9');

action(x,y)

This finds the URI defined by the map for the point at x and y. Returns undef if nothing matches. ie; no point and no default directives

  $action = $map->action($x, $y);

action throws an exception if there is an error. You should catch this with block eval and check $@

NOTES

NCSA Style Image Map Syntax

Blank lines and comments (start with #) are ignored. Each line in the map consists of a directive such as a shape name followed by the URI to associate with the shape and the points defining the shape. A point is an x,y tuple. Supported directives are

default URI

The URI for a selection not within any defined shape, if there are no point directives defined.

point URI point

Point objects do not themselves have to be clicked, instead if no shape was clicked the point closest to the clicked location matches.

circle URI centerPoint edgePoint

A circle with radius extending from centerPoint to edgePoint.

oval URI centerPoint xAxis, yAxis

An oval (ellipse) centered at centerPoint with the defined axes.

  oval 50,50 30,30

Is the same as

  circle 50,50 20,50

rect URI upperLeftPoint lowerRightPoint

A rectangle from upperleftPoint to lowerRightPoint. eg;

  rectangle 10,10 30,30

Is a rectangle with corners at 10,10 10,30 30,30 30,10

poly URI point1 point2 . . . pointN

A closed polygon defined by edges connecting points in the order listed. eg;

  poly 10,10 10,30 30,30 30,10

Is the same as the rectangle above.

The input coordinates are matched against the targets in the order which they were added to the object eg; read from the map file. This is normal behavior and so if you have overlapping shapes be sure to order them properly. Additionally, if you have complex non-overlapping shapes their order will affect the time to match. Place the simplest or most likely to be selected shapes first in your map file.

AUTHOR

Jerrad Pierce <jpierce@cpan.org>

CREDITS

Based upon CGI::Imagemap 1.00 by Mike Heins <mikeh@cpan.org>.

Who intern gladly reused code from imagemap.pl by V. Khera <khera@kciLink.com>.

Point in polygon detection based on code by Mike Lyons <lyonsm@netbistro.com>.

Point in oval detection based on code by Lynn Bry <lynn@pharmdec.wustl.edu>.