NAME
Apache::GD::Graph - Generate Charts in an Apache handler.
SYNOPSIS
In httpd.conf:
PerlModule Apache::GD::Graph
SetHandler perl-script
PerlHandler Apache::GD::Graph
# These are optional.
PerlSetVar Expires 30 # days.
PerlSetVar CacheSize 5242880 # 5 megs.
PerlSetVar ImageType png
# The default image type that graphs should be.
# png is default, gif requires <= GD 1.19.
# Any type supported by the installed version of GD will work.
PerlSetVar JpegQuality 75 # 0 to 100
# Best not to specify this one and let GD figure it out.
Then send requests to:
http://www.server.com/chart?type=lines&x_labels=[1st,2nd,3rd,4th,5th]&
data1=[1,2,3,4,5]&data2=[6,7,8,9,10]&dclrs=[blue,yellow,green]>
Options can also be sent as x-www-form-urlencoded data (ie., a
form). This works better for large data sets, and allows simple
charting forms to be set up. Parameters in the query string take
precedence over a form if specified.
INSTALLATION
Like any other CPAN module, if you are not familiar with CPAN
modules, see:
http://www.cpan.org/doc/manual/html/pod/perlmodinstall.html .
DESCRIPTION
The primary purpose of this module is to allow a very easy to
use, lightweight and fast charting capability for static pages,
dynamic pages and CGI scripts, with the chart creation process
abstracted and placed on any server.
For example, embedding a pie chart can be as simple as:
And it gets cached both server side, and along any proxies to
the client, and on the client's browser cache. Not to mention,
chart generation is very fast.
Of course, more complex things will be better done directly in
Perl.
Graphs Without Axes
To generate a graph without any axes, do not specify x_labels
and append `y_number_format=""' to your query. Eg.
http://www.some-server.com/chart?data1=[1,2,3,4,5]&y_number_format=""
Implementation
This module is implemented as a simple Apache mod_perl handler
that generates and returns a png format graph (using Martien
Verbruggen's GD::Graph module) based on the arguments passed in
via a query string. It responds with the content-type
"image/png" (or whatever is set via `PerlSetVar ImageType'), and
sends a Expires: header of 30 days (or whatever is set via
`PerlSetVar Expires', or expires in the query string, in days)
ahead.
In addition, it keeps a server-side cache in the file system
using DeWitt Clinton's File::Cache module, whose size can be
specified via `PerlSetVar CacheSize' in bytes.
OPTIONS
type Type of graph to generate, can be lines, bars, points,
linespoints, area, mixed, pie. For a description of
these, see the GD::Graph(3) manpage. Can also be one of
the 3d types if GD::Graph3d is installed, or anything
else with prefix GD::Graph::.
width Width of graph in pixels, 400 by default.
height Height of graph in pixels, 300 by default.
expires Date of Expires header from now, in days. Same as
`PerlSetVar Expires'.
image_type
Same as `PerlSetVar ImageType'. "png" by default, but
can be anything supported by GD.
If not specified via this option or in the config file,
the image type can also be deduced from a single value
in the 'Accept' header of the request.
jpeg_quality
Same as `PerlSetVar JpegQuality'. A number from 0 to 100
that determines the jpeg quality and the size. If not
set at all, the GD library will determine the optimal
setting. Changing this value doesn't seem to do much as
far as line graphs go, but YMMV.
cache Boolean value which determines whether or not the image will
get cached server-side (for client-side caching, use the
"expires" parameter). It is true (1) by default. Setting
`PerlSetVar CacheSize 0' in the config file will achieve
the same affect as `cache=0' in the query string.
to_file The graph will not be sent back, but instead saved to the
file indicated on the server. Apache will need
permission to write to that directory. The result will
not be cached. This is basically the same as making an
RPC call to a Perl process to make a graph and store it
to a file.
For the following, look at the plot method in the GD::Graph(3)
manpage.
x_labels
Labels used on the X axis, the first array given to the
plot method of GD::Graph. If unspecified or undef, no
labels will be drawn.
dataN Values to plot, where N is a number starting with 1. Can be
given any number of times with N increasing.
ALL OTHER OPTIONS are passed to the corresponding set_