view release on metacpan or  search on metacpan

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

              mercury_color => [ r, g, b ]
        });

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

=head2 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.

=head1 DIAGNOSTICS

=for author to fill in:
    List every single error and warning message that the module can
    generate (even the ones that will "never happen"), with a full
    explanation of each problem, one or more likely causes, and any
    suggested remedies.

=over

=item C<< 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.

=item C<< 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 C<< Error message here, perhaps with %s placeholders >>]

[Description of error here]

=back

=head1 CONFIGURATION AND ENVIRONMENT

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

=head1 DEPENDENCIES

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

=head1 INCOMPATIBILITIES

None reported.

=head1 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
C<bug-gd-graph-thermometer@rt.cpan.org>, or through the web
interface at L<http://rt.cpan.org>.

=head1 AUTHOR

Hugh Esco  C<< <hesco@campaignfoundations.com> >>

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

=head1 LICENCE AND COPYRIGHT

Copyright (c) 2007, Hugh Esco C<<
<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.