NAME

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

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

  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

    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

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

BUGS

AUTHOR

CREDITS