NAME

GD::Graph::Thermometer - Generate progress graph on the fly

VERSION

This document describes GD::Graph::Thermometer version 0.0.1

SYNOPSIS

    use GD::Graph::Thermometer;
    my $result = GD::Graph::Thermometer->new({
                 image_path => '/path/to/image.png',
                       type => 'png',
                       goal => '80000',
                    current => '20000',
                      title => 'Funding the League for the Year ($)',
                      width => '100',
                     height => '200',
                transparent => '1',
           background_color => [ r, g, b ],
                 text_color => [ r, g, b ],
              outline_color => [ r, g, b ],
              mercury_color => [ r, g, b ]
        });

DESCRIPTION

When deployed in production, the current value ought to be dynamically calculated based on a query of the database tracking contributions or volunteers or whatever the goal represented by the graph represents.

my $result = GD::Graph::Thermometer->new({});

This module exports only one method, its constructor, ->new(), which creates a .png (by default) image file of the thermometer graph with the path and name defined in its constructor. If no image_path is defined in the constructor, then the module will print the image directly to STDOUT.

The anonymous hash fed to the constructor must define values for the keys: goal and current. Otherwise a fatal error will be thrown. Current should represent the progress made toward the goal being graphed since the beginning of the campaign.

The output format defaults to png if the key 'type' is undefined, otherwise a user may specify png, gif or jpeg as the output format. These correspond to the GD::Image-> methods by the same name, which are used to implement the ->_render_image() internal method.

The size parameters will default to 100 pixels wide by 200 pixels tall, if those arguments are missing from the anonymous hash given to the constructor. If title is not defined a warning will be thrown, but the graph will still be generated.

The colors for the background, text, outline and mercury will default to white, black, black and red respectively, if not otherwise defined in the constructor. If defined in the constructor, they should be defined as an anonymous array of three values ( => [ r, g, b ],), range 0 - 255, suitable for feeding to the GD::Image->colorAllocate() method. If the transparent key is set to '1', any area of the image set to either the default or a custom background color will render as transparent for inclusion on a web page.

DIAGNOSTICS

Couldn't open file . . .

The system user under which this module was invoked does not have sufficient permission to write to the result image file. Make sure that the user has write permission on the target directory, or alternately, touch the file into existance and use chown and chmod to give write permissions on the result file itself to the user which will invoke the module. If this is run by your web server, that user is likely nobody, apache, www-data or something similiar.

The call to GD::Graph::Thermometer failed to define a title for the resulting graph.

Add "title => 'This is the title of my graph'," to your constructor, otherwise the module will throw this error and produce a graph without an explanatory title.

[=item Error message here, perhaps with %s placeholders]

[Description of error here]

CONFIGURATION AND ENVIRONMENT

GD::Graph::Thermometer requires no configuration files or environment variables.

DEPENDENCIES

This module depends on GD and GD::Text::Align.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

At present this module will produce a reasonable looking graphic when the image uses its default size (100 x 200 pixels). For reasons I don't yet quite understand, changing these arguments creates distorted images. Perhaps future development might address this issue.

Please report any bugs or feature requests to bug-gd-graph-thermometer@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Hugh Esco <hesco@campaignfoundations.com>

ACKNOWLEDGEMENTS

This module would not have been possible without the work of Lincoln Stein, who's GD:: heirarchy of modules makes this possible. And while I'm at it, let me also thank him for CGI.pm, which has made all of our lives much easier.

LICENCE AND COPYRIGHT

Copyright (c) 2007, Hugh Esco <hesco@campaignfoundations.com>. All rights reserved.

This module was created to serve an immediate need. However it is not central to the current focus of my development work. While I am not abandoning this code as unmaintained, I do invite others, particularly those with more experience developing modules in the GD:: heirarchy to consider adopting and maintaining this module. Please contact me by email if you are interested.

This module is free software; you can redistribute it and/or modify it under the terms of the Gnu Public License. See gpl.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm GD::Graph::Thermometer

perl -MCPAN -e shell
install GD::Graph::Thermometer