NAME
    Apache::GD::Graph - Generate Charts in an Apache handler.

SYNOPSIS
    In httpd.conf:

            PerlModule Apache::GD::Graph

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

            <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
    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_<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, marketingmoney.com, 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.

TODO
    If possible, a comprehensive test suite.

    Make it faster?

SEE ALSO
    the perl manpage, the GD::Graph manpage, the GD manpage