view release on metacpan or  search on metacpan

lib/Apache/GD/Graph.pm  view on Meta::CPAN

	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
allows simple charting forms to be set up, also, Internet Explorer does not
allow query strings larger than a kilobyte so in those cases a POSTED form must
be used.  Parameters in the query string take precedence over a form if
specified.

=head1 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 C<apachectl graceful> after
upgrading this or any other Apache Perl module.

=head1 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">
	<!-- All 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.

=head1 TIPS

Most more complicated things depend on knowing the GD::Graph interface.

Firstly, B<make sure you are not using any spaces!> If you want to pass a space in
a parameter in a URL-encoded string, use C<%20>, in a form use a C<+>.

Make sure to use C<cache=0> or C<PerlSetVar CacheSize 0> when debugging,
otherwise you will spend hours being very confused.

=head1 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).

The following fonts are built-in to GD, these strings will resolve into the
appropriate fonts except when quoted:

gdSmallFont, gdLargeFont, gdMediumBoldFont, gdTinyFont, gdGiantFont

There is also a way to use your own True Type Fonts. 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.

Fonts can also be specified as a relative path to the DocumentRoot of the
server, these must begin with "../". For example, if you have a directory
"fonts" under DocumentRoot, then you might specify a font like so:

	../fonts/arial.ttf

If DocumentRoot happens to be C</var/www> then the font that will be looked up
is C</var/www/fonts/arial.ttf>.

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, matches are case-insensitive. So if using the
Microsoft Windows core fonts, Arial Bold would be C<arialbd.ttf>. Here's an
example:

	http://server/chart?data1=[1,2,3,4,5]&
	title_font=(arialbd.ttf,20)&
	title=Just%20A%20Line

=head1 COLORS

All colors, including those specified for the captionN option, are specified
using the colour names from L<GD::Graph::colour>. They are, at time of writing:

white, lgray, gray, dgray, black, lblue, blue, dblue, gold, lyellow, yellow,
dyellow, lgreen, green, dgreen, lred, red, dred, lpurple, purple, dpurple,
lorange, orange, pink, dpink, marine, cyan, lbrown, dbrown.

=head1 IMAGES

You can place a logo in any corner of the graph using the C<logo>,
C<logo_resize> and C<logo_position> options. See L<GD::Graph>. If you just want
a background image that is resized to fit your graph, see the
C<background_image> option herein.

=head1 TEXT/CAPTIONS

The following GD::Graph options control placing text on the graph: title,
x_label and y_label. L<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.