The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Apache-GDGraph-0.91
River stage zero No dependents
/ Apache::GD::Graph

NAME

Apache::GD::Graph - Generate Graphs in an Apache handler.

SYNOPSIS

In httpd.conf:

        <Location /chart>
        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
        </Location>

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:

        <img src="http://www.some-server.com/chart?type=pie&
        x_labels=[greed,pride,wrath]&data1=[10,50,20]&dclrs=[green,purple,red]"
        alt="pie chart of a few deadly sins">
        <!-- Note that all of the above options are optional except for data1!  -->

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 GD::Graph. 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. GD::Graph 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 GD::Graph(3). 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 "FONTS" , $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 GD.

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 GD::Graph(3).

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_<option> method, or the set(<option hash>) method using the following rules for the values:

undef

Becomes a real undef.

[one,two,3]

Becomes an array reference.

(one,two,3)

This becomes a list, you can pass lists to set_SOMETHING methods of GD::Graph, if there is no corresponding set_ method, the list will be silently converted to an anonymous array and used in an ordinary option.

{one,1,two,2}

Becomes a hash reference.

http://somewhere/file.png

Is pulled into a file and the file name is passed to the respective option. (Can be any scheme besides http:// that LWP::Simple supports.)

[undef,something,undef] or {key,undef}

You can create an array or hash with undefs.

['foo',bar] or 'baz' or {'key','value'}

Single and double quoted strings are supported, either as singleton values or inside arrays and hashes.

DON'T USE SPACES, this is a common mistake. A space in a URL-encoded string is %20, or a + in a form.

Nested structures are still not supported, maybe later.

AUTHOR

Rafael Kitover (caelum@debian.org)

COPYRIGHT

This program is Copyright (c) 2000 by Rafael Kitover. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

ACKNOWLEDGEMENTS

This module owes its existance, obviously, to the availability of the wonderful GD::Graph module from Martien Verbruggen <mgjv@comdyn.com.au>.

Thanks to my employer, Gradience, Inc., for allowing me to work on projects as free software.

Thanks to Vivek Khera (khera@kciLink.com) and Scott Holdren <scott@monsterlabs.com> for the bug fixes.

BUGS

Probably a few.

We should probably just let people set up their own PerlFixupHandlers for errors, but this makes it more difficult to set up. At least, it should be an option.

TODO

Boxed captions. Variable mapping of x-labels to data points. If possible, a comprehensive test suite. Make it faster?

SEE ALSO

perl, GD::Graph, GD