[Jifty-commit] r3731 - in jifty/trunk: . lib/Jifty/Plugin
lib/Jifty/Plugin/Chart/Renderer
jifty-commit at lists.jifty.org
jifty-commit at lists.jifty.org
Sun Jul 29 16:16:00 EDT 2007
Author: sterling
Date: Sun Jul 29 16:15:59 2007
New Revision: 3731
Modified:
jifty/trunk/ (props changed)
jifty/trunk/lib/Jifty/Plugin/Chart.pm
jifty/trunk/lib/Jifty/Plugin/Chart/Dispatcher.pm
jifty/trunk/lib/Jifty/Plugin/Chart/Renderer.pm
jifty/trunk/lib/Jifty/Plugin/Chart/Renderer/Chart.pm
jifty/trunk/lib/Jifty/Plugin/Chart/View.pm
jifty/trunk/lib/Jifty/Plugin/Chart/Web.pm
Log:
r8199 at dynpc145: andrew | 2007-07-29 15:13:38 -0500
Added documentation to the experimental Chart plugin.
Modified: jifty/trunk/lib/Jifty/Plugin/Chart.pm
==============================================================================
--- jifty/trunk/lib/Jifty/Plugin/Chart.pm (original)
+++ jifty/trunk/lib/Jifty/Plugin/Chart.pm Sun Jul 29 16:15:59 2007
@@ -6,6 +6,56 @@
use Jifty::Plugin::Chart::Web;
+=head1 NAME
+
+Jifty::Plugin::Chart - A charting API for Jifty
+
+=head1 SYNOPSIS
+
+In your F<config.yml>:
+
+ Plugins:
+ - Chart: {}
+
+In your Mason templates:
+
+ <% Jifty->web->chart(
+ type => 'Bar',
+ width => 400,
+ height => 300,
+ data => [
+ [ '2004', '2005', '2006', '2007' ], # labels
+ [ 14, 15, 17, 22 ], # first data set
+ [ 22, 25, 20, 21 ], # second data set
+ ],
+ ) %>
+
+=head1 DESCRIPTION
+
+B<CAUTION:> This plugin is experimental. The API I<will> change.
+
+This plugin provides a charting API that can be used by Jifty applications to build data visualizations without regard to the underlying rendering mechanism.
+
+As of this writing, the API is a barely veiled interface over L<Chart>. However, I intend to expand the interface to apply to something like Maani's XML/SWF Charts or Imprise Javascript charts or even something like OpenLaszlo (or something Open Source and Perl if I can find or build such a thing in time).
+
+=head1 INTERFACE
+
+By adding this method to the plugin configuration for your Jifty application, you will cause L<Jifty::Web> to inherit a new method, C<chart>, which is the cornerstone of this API.
+
+This method is described in L<Jifty::Plugin::Chart::Web> and an example is shown in the L</SYNOPSIS> above.
+
+=head1 CONFIGURATION
+
+The plugin takes a single configuration option called C<renderer>. This may be set to a chart renderer class, which is just an implementation of L<Jifty::Plugin::Chart::Renderer>. The default, L<Jifty::Plugin::Chart::Renderer::Chart>, uses L<Chart> to render charts as PNG files which are then included in your pages for you.
+
+Here is an example configuration for F<config.yml>:
+
+ Plugins:
+ - Chart:
+ renderer: Jifty::Plugin::Chart::Renderer::Chart
+
+=cut
+
__PACKAGE__->mk_accessors(qw/ renderer /);
sub init {
@@ -27,4 +77,20 @@
$self->renderer->render(@_);
}
+=head1 SEE ALSO
+
+L<Jifty::Plugin>, L<Jifty::Web>, L<Jifty::Plugin::Chart::Renderer>, L<Jifty::Plugin::Chart::Renderer::Chart>, L<Jifty::Plugin::Chart::View>
+
+=head1 AUTHOR
+
+Andrew Sterling Hanenkamp E<< <andrew.hanenkamp at boomer.com> >>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2007 Boomer Consulting, Inc.
+
+This is free software and may be modified and redistributed under the same terms as Perl itself.
+
+=cut
+
1;
Modified: jifty/trunk/lib/Jifty/Plugin/Chart/Dispatcher.pm
==============================================================================
--- jifty/trunk/lib/Jifty/Plugin/Chart/Dispatcher.pm (original)
+++ jifty/trunk/lib/Jifty/Plugin/Chart/Dispatcher.pm Sun Jul 29 16:15:59 2007
@@ -6,6 +6,18 @@
use Jifty::YAML;
+=head1 NAME
+
+Jifty::Plugin::Chart::Dispatcher - Dispatcher for the chart API plugin
+
+=head1 RULES
+
+=head2 chart/*
+
+Grabs the chart configuration stored in the key indicated in C<$1> and unpacks it using L<YAML>. It then passes it to the L<Jifty::Plugin::Chart::View/chart> template.
+
+=cut
+
on 'chart/*' => run {
my $session_id = 'chart_' . $1;
@@ -18,4 +30,20 @@
show 'chart';
};
+=head1 SEE ALSO
+
+L<Jifty::Plugin::Chart::View>
+
+=head1 AUTHOR
+
+Andrew Sterling Hanenkamp E<< <andrew.hanenkamp at boomer.com> >>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2007 Boomer Consulting, Inc.
+
+This is free software and may be modified and redistributed under the same terms as Perl itself.
+
+=cut
+
1;
Modified: jifty/trunk/lib/Jifty/Plugin/Chart/Renderer.pm
==============================================================================
--- jifty/trunk/lib/Jifty/Plugin/Chart/Renderer.pm (original)
+++ jifty/trunk/lib/Jifty/Plugin/Chart/Renderer.pm Sun Jul 29 16:15:59 2007
@@ -3,4 +3,66 @@
package Jifty::Plugin::Chart::Renderer;
+=head1 NAME
+
+Jifty::Plugin::Chart::Renderer - Base class for chart rendering classes
+
+=head1 SYNOPSIS
+
+In your F<config.yml>:
+
+ Plugins:
+ - Chart:
+ renderer: MyApp::Renderer;
+
+In F<lib/MyApp/Renderer.pm>:
+
+ package MyApp::Renderer;
+ use base qw/ Jifty::Plugin::Chart::Renderer /;
+
+ sub render {
+ my $self = shift;
+ my %args = (
+ type => 'points',
+ width => 400,
+ height => 300,
+ data => [],
+ @_,
+ );
+
+ # Output your chart
+ Jifty->web->out( #{ Output your chart here... } );
+
+ # You could also return it as a string...
+ return;
+ }
+
+=head1 METHODS
+
+Your renderer implementation must subclass this package and implement the following methods:
+
+=head2 render
+
+ Jifty->web->out($renderer->render(%args));
+
+See L<Jifty::Plugin::Chart::Web> for the arguments. It must (at least) accept the arguments given to the L<Jifty::Plugin::Chart::Web/chart> method.
+
+The C<render> method may either return it's output or print it out using L<Jifty::Web::out>.
+
+=head1 SEE ALSO
+
+L<Jifty::Plugin::Chart::Web>, L<Jifty::Plugin::Chart::Renderer::Chart>
+
+=head1 AUTHOR
+
+Andrew Sterling Hanenkamp C<< <andrew.hanenkamp at boomer.com> >>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2007 Boomer Consulting, Inc.
+
+This is free software and may be modified and distributed under the same terms as Perl itself.
+
+=cut
+
1;
Modified: jifty/trunk/lib/Jifty/Plugin/Chart/Renderer/Chart.pm
==============================================================================
--- jifty/trunk/lib/Jifty/Plugin/Chart/Renderer/Chart.pm (original)
+++ jifty/trunk/lib/Jifty/Plugin/Chart/Renderer/Chart.pm Sun Jul 29 16:15:59 2007
@@ -6,27 +6,60 @@
use Jifty::YAML;
+=head1 NAME
+
+Jifty::Plugin::Chart::Renderer::Chart - A chart renderer using PNG charts
+
+=head1 DESCRIPTION
+
+This is the default chart renderer used by the L<Jifty::Plugin::Chart> plugin. It works by rendering an IMG tag in the HTML output, which then points to a URL which, when dispatched, retrieves the stored configuration and renders the chart using the L<Chart> package.
+
+=head1 METHODS
+
+=head2 render
+
+Implemented the L<Jifty::Plugin::Chart::Renderer/render> method interface.
+
+=cut
+
sub render {
my $self = shift;
- my %args = (
- type => 'points',
- width => 400,
- height => 300,
- data => [],
- @_,
- );
+ my %args = @_;
+ # Turn any subs into values returned
for my $key (keys %args) {
$args{$key} = $args{$key}->(\%args) if ref $args{$key} eq 'CODE';
}
+ # Make sure the type is ready to be used as a class name
+ $args{type} = ucfirst lc $args{type};
+
+ # Save the data for retrieval from the session later
my $chart_id = Jifty->web->serial;
my $session_id = 'chart_' . $chart_id;
Jifty->web->session->set( $session_id => Jifty::YAML::Dump(\%args) );
+ # Output the <img> tag and include the chart's configuration key
Jifty->web->out(qq{<img src="/chart/$chart_id" width="$args{width}" height="$args{height}"/>});
+ # Make sure we don't return anything that will get output
return;
}
+=head1 SEE ALSO
+
+L<Jifty::Plugin::Chart>, L<Jifty::Plugin::Chart::Renderer>
+
+=head1 AUTHOR
+
+Andrew Sterling Hanenkamp C<< <andrew.hanenkamp at boomer.com> >>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2007 Boomer Consulting, Inc.
+
+This is free software and may be modified and distributed under the same terms as Perl itself.
+
+=cut
+
1;
Modified: jifty/trunk/lib/Jifty/Plugin/Chart/View.pm
==============================================================================
--- jifty/trunk/lib/Jifty/Plugin/Chart/View.pm (original)
+++ jifty/trunk/lib/Jifty/Plugin/Chart/View.pm Sun Jul 29 16:15:59 2007
@@ -6,20 +6,55 @@
use IO::String;
+=head1 NAME
+
+Jifty::Plugin::Chart::View - Views for the renderers built into the Chart plugin
+
+=head1 TEMPLATES
+
+=head2 chart
+
+This shows a chart using L<Chart>. It expects to find the arguments in the C<args> parameter, which is setup for it in L<Jifty::Plugin::Chart::Dispatcher>.
+
+This will output a PNG file unless there is an error building the chart.
+
+=cut
+
template 'chart' => sub {
+ # Load the arguments
my $args = get 'args';
+ # Use the "type" to determine which class to use
my $class = 'Chart::' . $args->{type};
+ # Load that class or die if it does not exist
eval "use $class";
die $@ if $@;
+ # Set the output type to the PNG file type
Jifty->handler->apache->content_type('image/png');
+ # Render the chart and output the PNG file generated
my $fh = IO::String->new;
my $chart = $class->new( $args->{width}, $args->{height} );
$chart->png($fh, $args->{data});
outs_raw( ${ $fh->string_ref } )
};
+=head1 SEE ALSO
+
+L<Jifty::Plugin::Chart::Dispatcher>
+
+=head1 AUTHOR
+
+Andrew Sterling Hanenkamp C<< <andrew.hanenkamp at boomer.com> >>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2007 Boomer Consulting, Inc.
+
+This is free software and may be modified and distributed under the same terms as Perl itself.
+
+=cut
+
1;
Modified: jifty/trunk/lib/Jifty/Plugin/Chart/Web.pm
==============================================================================
--- jifty/trunk/lib/Jifty/Plugin/Chart/Web.pm (original)
+++ jifty/trunk/lib/Jifty/Plugin/Chart/Web.pm Sun Jul 29 16:15:59 2007
@@ -3,10 +3,122 @@
package Jifty::Plugin::Chart::Web;
+=head1 NAME
+
+Jifty::Plugin::Chart::Web - Base class to add to Jifty::Web's ISA
+
+=head1 DESCRIPTION
+
+When the L<Jifty::Plugin::Chart> is loaded, this class is added as a base class for L<Jifty::Web> to add the L</chart> method to that class.
+
+=head1 METHODS
+
+=head2 chart
+
+ Jifty->web->out(Jifty->web->chart(%args));
+
+The arguments passed in C<%args> may include:
+
+=over
+
+=item type
+
+This will be one of the following scalar values indicating the kind of chart:
+
+=over
+
+=item Points
+
+This is the default value. A scatter plot with each dataset represented using differnet dot styles.
+
+=item Lines
+
+A line plot with each dataset presented as separate line.
+
+=item Bars
+
+A bar chart with each dataset set side-by-side.
+
+=item StackedBars
+
+A bar chart with each dataset stacked on top of each other.
+
+=item Pie
+
+A pie chart with a single dataset representing the values for different pieces of the pie.
+
+=item HorizontalBars
+
+A bar chart turned sideways.
+
+=back
+
+=item width
+
+The width, in pixels, the chart should take on the page. Defaults to 400.
+
+=item height
+
+The height, in pixels, the chart should take on the page. Defaults to 300.
+
+=item data
+
+An array of arrays containing the data. The first array in the parent array is a list of labels. Each following array is the set of data points matching each label in the first array.
+
+Defaults to no data (i.e., it must be given if anything useful is to happen).
+
+=back
+
+Here's an example:
+
+ <% Jifty->web->chart(
+ type => 'Pie',
+ width => 400,
+ height => 300,
+ data => sub {
+ [
+ [ 2004, 2005, 2006, 2007 ],
+ [ 26, 37, 12, 42 ]
+ ];
+ },
+ ) %>
+
+Be sure to output anything returned by the method (unless it returns undef).
+
+=cut
+
sub chart {
my $self = shift;
my ($plugin) = Jifty->find_plugin('Jifty::Plugin::Chart');
+
+ # TODO It might be a good idea to make this config.yml-able
+ # Setup the defaults
+ my %args = (
+ type => 'points',
+ width => 400,
+ height => 300,
+ data => [],
+ @_,
+ );
+
+ # Call the rendering plugin's render method
return $plugin->render(@_);
}
+=head1 SEE ALSO
+
+L<Jifty::Plugin::Chart>, L<Jifty::Plugin::Chart::Renderer>
+
+=head1 AUTHOR
+
+Andrew Sterling Hanenkamp C<< <andrew.hanenkamp at boomer.com> >>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2007 Boomer Consulting, Inc.
+
+This is free software and may be modified and distributed under the same terms as Perl itself.
+
+=cut
+
1;
More information about the Jifty-commit
mailing list