NAME
Apache::GD::Graph - Generate Graphs in an Apache handler.
SYNOPSIS
In httpd.conf:
SetHandler perl-script
PerlHandler +Apache::GD::Graph
# These are optional.
#PerlSetVar Expires 30 # days default.
#PerlSetVar CacheSize 5242880 # 5 megs default.
#PerlSetVar ImageType png # Default.
# 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.
#
# The next specifies the quality of generated JPEG images, best not to
# specify this one and let GD figure it out.
#PerlSetVar JpegQuality 75 # 0 to 100
# TTFFontPath tells GD::Text where to look for true type fonts. The
# example here is the default value used.
#PerlSetVar TTFFontPath /usr/ttfonts:/var/ttfonts:/usr/X11R6/lib/X11/fonts/ttf/:/usr/X11R6/lib/X11/fonts/truetype/:/usr/share/fonts/truetype
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. IE, for example, does not allow query
strings larger than a kilobyte. 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
MAKE SURE TO RESTART YOUR APACHE SERVER using `apachectl graceful'
after upgrading this or any other Apache Perl module.
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 your
own Perl handlers, but this module allows a non-Perl environment to
have access to the capabilities of GD::Graph.
Another solution is to use ASP scripting with Microsoft Excel, which
of course requires a Windows NT server and I have no idea how easy
this is to do, or how fast.
There are also many other ways to connect programs with charting
capabilities, such as GNUPlot, or rrdtool to a web server. These may
or may not be faster/more featureful etc.
TIPS
Most more complicated things depend on knowing the GD::Graph
interface.
Firstly, make sure you are not using any spaces! If you want to pass
a space in a parameter in a URL-encoded string, use `%20', in a form
use a `+'.
Make sure to use `cache=0' or `PerlSetVar CacheSize 0' when
debugging, otherwise you will spend hours being very confused.
FONTS
GD::Graph has some options that take a font description, such as
title_font, legend_font, etc. (these map to the appropriate set_FOO
methods in GD::Graph, see that manpage). See the TTFFontPath
variable under SYNOPSIS for how to set the search path for fonts.
MAKE SURE your fonts are readable by the user the Apache server runs
under, this is usually "www-data" or "nobody". Otherwise your fonts
will mysteriously fail with no notice.
Sizes can be specified by using a list with the name and size. For
example, if arial.ttf can be found somewhere in your TTFFontPath,
you can do:
...title_font=(arial.ttf,20)
To get a title using font Arial, in 20 points.
Note that GD::Text does not parse out the names of fonts and such,
you have to give it an actual filename, in the right case. So if
using the Microsoft Windows core fonts, Arial Bold would be
`arialbd.ttf'. Here's an example:
http://server/chart?data1=[1,2,3,4,5]&title_font=(arialbd.ttf,20)&title=Just%20A%20Line
IMAGES
You can place a logo in any corner of the graph using the `logo',
`logo_resize' and `logo_position' options. See the GD::Graph
manpage. If you just want a background image that is resized to fit
your graph, see the `background_image' option herein.
TEXT/CAPTIONS
The following GD::Graph options control placing text on the graph:
title, x_label and y_label. the GD::Graph manpage for those and
related options. In addition, this modules allows you to use the
captionN option(s), to draw arbitrary strings on the graph. See
below.
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.
background_image
Set an image as the background for the graph. You are
responsible for choosing a sane image to go with your graph,
the background should be either transparent or the same
color you will use. This is the same as using the `logo'
parameter with an image of the same size as the graph,
except this option will resize the image if necessary,
making it more convenient for this purpose. The file or URL
can be of any type your copy of GD supports.
captionN
Draws a character string using a TrueType font at an
arbitrary location. Takes an array of
`($fgcolor,$fontname,$ptsize,$angle,$x,$y,$string)' where
$fgcolor is the foreground color, $fontname is the name of a
TTF font see the FONTS entry elsewhere in this document ,
$ptsize is the point size, $x and $y are the coordinates,
and $string is the actual characters to draw.
N is an integer from 1 onward, like for the dataN option.
This lets you specify multiple strings to draw.
This follows exactly the GD stringTTF method, see the GD
manpage.
Angle is in degrees, you will primarily use angle `0' for
normal left-to-right text. $x and $y are pixel coordinates
from the upper left corner. $fontname is the name of a
true-type font that will be found in the font path (see
FONTS). Example:
http://isis/chart?data1=[1,2,3,4,5]&caption1=(1,arial.ttf,9,0,30,30,Hello)
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.
no_axes This sets x_labels to an empty lists and sets
y_number_format to "", effectively disabling axes labels.
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_