NAME

GD::Graph::Map - generate HTML map text for GD::Graph diagramms.

SYNOPSIS

use GD::Graph::Map;

$map = new GD::Graph::Map($gr_object);

$map->set(key1 => value1, key2 => value2 ...);

$HTML_map = $map->imagemap($gr_file, \@data);

DESCRIPTION

This is a perl5 module to generate HTML map text for following GD::Graph objects GD::Graph::pie, GD::Graph::bars, GD::Graph::lines, GD::Graph::area, GD::Graph::point and GD::Graph::linespoints. As a result of its work is created HTML code containing IMG and MAP tags. You simply need to insert this code into the necessary place of your HTML page. In the inserted thus image, its certain parts are the references and at a choice their mouse in a status line of your browser displays the additional information (see Samples).

SAMPLES

See the samples directory in the distribution.

USAGE

First of all you must create the GD::Graph object and set options if it is necessary. Then create array of data and use plot routine for create graph image. For example create GD::Graph::pie object:

  $graph = new GD::Graph::pie;

  $graph->set('title'        => 'A Pie Chart',
              'label'        => 'Label',
              'axislabelclr' => 'black',
              'pie_height'   => 80);

  @data = (["1st","2nd","3rd","4th","5th","6th"],
           [    4,    2,    3,    4,    3,  3.5]);

  $PNGimage = 'Demo.png';
  open PNG, '>$pngimage';
  binmode PNG; #only for Windows like platforms
  print PNG $graph->plot(\@data)->png;
  close PNG;

Then create GD::Graph::Map object. And set options using set routine, or set it in constructor immediately. If it is necessary create hrefs and legend arrays:

  $map = new GD::Graph::Map($graph, newWindow => 1);

  $map->set(info => "%x slice contains %.1p% of %s (%x)");

Create HTML map text using the same array of data as use GD::Graph::plot routine and name of the your graph file:

  $HTML_map = $map->imagemap($GIFimage, \@data);

Now you can insert $HTML_map into the necessary place of your HTML page. You also can create only MAP tag with determined by you map name. For more information look at noImgMarkup and mapName options of the set routine.

METHODS AND FUNCTIONS

Constructor

Constructor of object has following syntax:

  new GD::Graph::Map($gr_object,
    [key1 => value1, key2 => value2 ...]);

where $gr_object this is one of the following graph objects: GD::Graph::pie, GD::Graph::bars, GD::Graph::lines, GD::Graph::area, GD::Graph::point or GD::Graph::linespoints; key1, value1 ... the same as using in the set routine. NOTE: Before use constructor you should at first set all properties for graph object, because they will be using for generetaing properly HTML map.

imagemap($gr_file, \@data)

Generate HTML map text using the graph file $file and reference to array of data - \@data, which must be the same as using in plot routine.

set(key1 => value1, key2 => value2 .... )

Set options. See OPTIONS.

OPTIONS

hrefs, lhrefs

Sets hyper reference for each data (hrefs), and for each legend (lhrefs). Array @hrefs must the same size as arrays in @data list, otherwise null elements of @hrefs will set to default. Similarly array @lhrefs must the same size as the legend array. Default uses the simple JavaScript code 'javascript:;' instead reference, which do nothing (but in the some browsers it can work incorrectly).

Example of @hrefs array:

for the GD::Graph::pie object:

if @data = ([ "1st", "2nd", "3rd"], [ 4, 2, 3]);

then @hrefs = ["1.htm","2.htm","3.htm"];

for the other objects:

if @data = ([ "1st", "2nd", "3rd"], [ 5, 12, 24], [ 1, 2, 5]);

then @hrefs = (["1.htm","2.htm","3.htm"], ["4.htm","5.htm","6.htm"]);

Example of @lhrefs array;

if @legend = [ 'one', 'two','three'];

then @lhrefs = ["1.htm","2.htm","3.htm"];

info, legend

Set information string for the data and for the legend. It will be displayed in the status line of your browser. Format of this string the same for each data, but you can use special symbols for receive individual information. Now available following symbols: %x - Will be replaced on the x values in @data (first array) %y - Will be replaced on the y values in @data (other arrays) %s - Will be replaced on the sum of all y values. %l - Will be replaced on the legend. For all objects, except the GD::Graph::pie object. %p - Will be replaced on the value, which show what part from all contains this data (in percentages).

%s and %p symbols can useing only in the GD::Graph::pie object. %l symbol vice versa available for all objects, except the GD::Graph::pie object. And %x, %y symbols available for all objects, except the GD::Graph::lines and the GD::Graph::area objects. For the numerical parameters (%x, %y, %s and %p) you can use special format (the same as uses sprintf routine) for round data: %.d{x|y|p|s}, where 'd' is a digit from 0 to 9. For example %.0p or %.3x. It is desirable uses if %x, %y, %s or %p is the floating numbers. Default is 'x=%x y=%y' for info, and '%l' for legend.

img_*

You can set any attribute in the IMG tag (except UseMap, Src, Width, Height and Border, they will be set automatically) use set routine: set(img_option => value), where 'option' is the IMG attribute. For instance: routine set(img_Alt => 'Example') will include Alt='Example' in the IMG tag.

newWindow, window_*

If the newWindow attribute is set to the TRUE and link does not contains JavaScript code (like javascript:), that link will be open in the new navigator window. Parameters of the new window you can establish using the window_* parameters, similarly the img_*.

mapName

If mapName is TRUE the map will have this name. Default is time().

noImgMarkup

If noImgMarkup is TRUE will be printed only the MAP tag, without the <Img UseMap=... > markup. You will have to print your own. Useful if the Graph is generated and poured directly to the a web-browser and not plotted to a GIF file.

AUTHOR

Roman Kosenko

Contact info

E-mail: ra@amk.lg.ua

Home page: http://amk.lg.ua/~ra/Map

Copyright

Copyright (C) 1999 Roman Kosenko. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm GD::Graph::Map

perl -MCPAN -e shell
install GD::Graph::Map