From dfcd338e0693370eeaa95ca1f4ef8c742221b348 Mon Sep 17 00:00:00 2001
From: Simon Cozens <simon@simon-cozens.org>
Date: Fri, 2 Apr 2004 17:53:44 +0000
Subject: [PATCH] Finished view documentation, refactor TT->base, and add Mason
 view class.

git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@113 48953598-375a-da11-a14b-00016c27c3ee
---
 doc/View.pod              | 93 +++++++++++++++++++++++++++++++++++--
 lib/Maypole/View/Base.pm  | 87 +++++++++++++++++++++++++++++++++++
 lib/Maypole/View/Mason.pm | 61 ++++++++++++++++++++++++
 lib/Maypole/View/TT.pm    | 97 +++++++++++----------------------------
 4 files changed, 264 insertions(+), 74 deletions(-)
 create mode 100644 lib/Maypole/View/Base.pm
 create mode 100644 lib/Maypole/View/Mason.pm

diff --git a/doc/View.pod b/doc/View.pod
index d2fda75..c469100 100644
--- a/doc/View.pod
+++ b/doc/View.pod
@@ -420,8 +420,91 @@ system which embeds pure Perl code inside its magic tags. The good side
 of this is that it can get into hash references and objects, and so
 providing C<classmetadata>, C<config> and the Maypole request object
 will work out just fine. The down side is that C<HTML::Mason> is used to
-having all the template variables it wants already at its disposal
-through CGI parameters and the like, so we have to fiddle a bit to get
-these variables into our template.
-
-
+running more or less standalone, and having all the template variables
+it wants already at its disposal through CGI parameters and the like, so
+we have to fiddle a bit to get these variables into our template.
+
+The key to building view classes is C<Maypole::View::Base>. This is the
+base class that you're going to inherit from and, to be honest, it does
+pretty much everything you need. It provides a method called C<vars>
+which returns a hash of all the template variables described above, so
+it would be good to feed those into C<HTML::Mason>. It also provides a
+C<paths> method which turns returns the full filesystem path of the
+three possible template paths as shown above. Again, it would be good to
+use this as our component paths if we can. It also has some methods we
+can override if we want to, but they're not massively important, so you
+can see L<Maypole::View::Base> for more about them. 
+
+The module will do the right thing for us if we agree to provide a
+method called C<template>. This is responsible for taking the Maypole
+request object (of which more later) and putting the appropriate output
+either into C<$r-E<gt>{output}> or C<$r-E<gt>{error}>, depending, of
+course, whether things are OK or whether we got an error.
+
+Thankfully, C<HTML::Mason> makes things really easy for us. We B<can>
+use multiple template roots, so we can use the C<paths> method; we
+B<can> pass in a hash full of interesting data structures, so we can use
+the C<vars> method too. In fact, we have to do very little to make
+C<Maypole::View::Mason> work. Which is somewhat annoying, because it
+makes a boring example. But it means I can leave the fun ones to you!
+
+The doing-the-templating, in Mason and in any templating system, depends on
+three things: the paths that we're going to use to find our templates, the
+template name that we've been asked to fill out, and the set of variables that
+are going to be fed to the template. We'll assemble these for reference:
+
+    sub template {
+        my ($self, $r) = @_;
+        my @paths = $self->paths($r);
+        my $template = $r->template;
+        my %vars = $self->args($r);
+
+We'll also declare somewhere to temporarily store the output:
+
+        my $output;
+
+Now comes the part where we have to actually do something
+templating-language specific, so we open up our copy of "Embedding Perl
+in HTML with Mason" and find the bit where it talks about running Mason
+standalone. We find that the first thing we need to do is create a
+C<HTML::Mason::Interp> object which knows about the component roots.
+There's a slight subtlety in that the component roots have to be
+specified as an array of arrays, with each array being a two-element
+list of label and path, like so:
+
+    comproot => [
+        [ class   => "/var/www/beerdb/templates/brewery" ],
+        [ custom  => "/var/www/beerdb/templates/custom" ],
+        [ factory => "/var/www/beerdb/templates/factory" ],
+    ]
+
+We also find that we can set the output method here to capture Mason's
+output into a scalar, and also that we can tell Mason to generate
+sensible error messages itself, which saves us from having to worry
+about catching errors. At the end of all this, we come up with a
+constructor for our C<HTML::Mason::Interp> object which looks like this:
+
+    my $label = "path0";
+    my $mason = HTML::Mason::Interp->new(
+        comproot => [ map { [ $label++ => $_ ] } @paths ],
+        output_method => \$output,
+        error_mode => "output" 
+    );
+
+The next thing we need to do is run the template with the appropriate
+template variables. This turns out to be really easy:
+
+    $mason->exec($template, %vars);
+
+Now we've got the data in C<$output>, we can put it into the request object,
+and return a true value to indicate that we processed everything OK. (If there
+was an error, then Mason will have produced some suitable output, so we can
+pretend that everything's OK anyway.)
+
+    $r->{output} = $output;
+    return 1;
+
+And that's all we need to do. Barely twenty lines of code for the finished
+product. Wasn't that easy? Don't you feel inspired to write Maypole view
+classes for your favourite templating language? Well, don't let me stop you!
+Patches are always welcome!
diff --git a/lib/Maypole/View/Base.pm b/lib/Maypole/View/Base.pm
new file mode 100644
index 0000000..eaff544
--- /dev/null
+++ b/lib/Maypole/View/Base.pm
@@ -0,0 +1,87 @@
+package Maypole::View::Base;
+use File::Spec;
+use UNIVERSAL::moniker;
+use strict;
+
+sub new { bless {}, shift } # By default, do nothing.
+
+sub paths {
+    my ($self, $r) = @_;
+    my $root = $r->{config}{template_root} || $r->get_template_root;
+    return (
+        $root,
+        ($r->model_class && 
+            File::Spec->catdir($root, $r->model_class->moniker)),
+        File::Spec->catdir($root, "custom"),
+        File::Spec->catdir($root, "factory")
+    );
+}
+
+sub vars {
+    my ($self, $r) = @_;
+    my $class = $r->model_class;
+    my %args = (
+        request => $r,
+        objects => $r->objects,
+        base    => $r->config->{uri_base},
+        config  => $r->config
+        # ...
+    ) ;
+    if ($class) { 
+        $args{classmetadata} = {
+            name => $class,
+            table => $class->table,
+            columns => [ $class->display_columns ],
+            colnames => { $class->column_names },
+            related_accessors => [ $class->related($r) ],
+            moniker => $class->moniker,
+            plural  => $class->plural_moniker,
+            cgi => { $class->to_cgi },
+            description => $class->description
+        };
+
+        # User-friendliness facility for custom template writers.
+        if (@{$r->objects || []} > 1) { 
+            $args{$r->model_class->plural_moniker} = $r->objects;
+        } else {
+            ($args{$r->model_class->moniker}) = @{$r->objects ||[]};
+        }
+    }
+
+    # Overrides
+    %args = (%args, %{$r->{template_args}||{}});
+    %args;
+}
+
+sub do_it {
+    my ($self, $r) = @_;
+    my $template = Template->new({ INCLUDE_PATH => [ $self->paths($r) ]});
+    my $output;
+    if ($template->process($r->template, { $self->args($r) }, \$output)) {
+        $r->{output} = $output;
+        return 1;
+    } else { 
+         $r->{error} = $template->error;
+    }
+
+}
+
+sub process {
+    my ($self, $r) = @_;
+    $self->template($r) || return $self->error($r);
+    $r->{content_type} ||= "text/html";
+    return 200;
+}
+
+sub error {
+    my ($self, $r) = @_;
+    warn $r->{error};
+    if ($r->{error} =~ /not found$/) { return -1 }
+    $r->{content_type} = "text/plain";
+    $r->{output} = $r->{error};
+    $r->send_output;
+}
+
+sub template { die shift()." didn't define a decent template method!" }
+
+1;
diff --git a/lib/Maypole/View/Mason.pm b/lib/Maypole/View/Mason.pm
new file mode 100644
index 0000000..4d50bbd
--- /dev/null
+++ b/lib/Maypole/View/Mason.pm
@@ -0,0 +1,61 @@
+package Maypole::View::Mason;
+use base 'Maypole::View::Base';
+use HTML::Mason;
+
+sub template {
+    my ($self, $r) = @_;
+    my $label = "path0";
+    my $output;
+    my $mason = HTML::Mason::Interp->new(
+        comproot => [ map { [ $label++ => $_ ] } $self->paths($t) ],
+        output_method => \$output,
+        error_mode => "output" # Saves us having to handle them...
+    );
+    $mason->exec($r->template, $self->vars($r))
+    $r->{output} = $output;
+    return 1;
+}
+
+1;
+
+=head1 NAME
+
+Maypole::View::Mason - A HTML::Mason view class for Maypole
+
+=head1 SYNOPSIS
+
+   BeerDB->config->{view} = "Maypole::View::Mason"; 
+
+And then:
+
+    <%args>
+        @breweries
+    </%args>
+
+    % for my $brewery (@breweries) {
+        ...
+        <TD><% $brewery->name %></TD>
+    % }
+    ...
+
+=head1 DESCRIPTION
+
+This class allows you to use C<HTML::Mason> components for your Maypole
+templates. It provides precisely the same path searching and template
+variables as the Template Toolkit view class, although you will need
+to produce your own set of templates as the factory-supplied templates
+are, of course, Template Toolkit ones. 
+
+Please see the Maypole manual, and in particular, the C<View> chapter,
+for the template variables available and for a refresher on how template
+components are resolved.
+
+=head1 AUTHOR
+
+Simon Cozens
+
+=head1 THANKS
+
+This module was made possible thanks to a Perl Foundation grant.
+
+=cut
diff --git a/lib/Maypole/View/TT.pm b/lib/Maypole/View/TT.pm
index a1960ba..15581e8 100644
--- a/lib/Maypole/View/TT.pm
+++ b/lib/Maypole/View/TT.pm
@@ -1,81 +1,40 @@
 package Maypole::View::TT;
-use Lingua::EN::Inflect;
+use base 'Maypole::View::Base';
 use Template;
-use File::Spec;
-use UNIVERSAL::moniker;
-use strict;
 
-
-sub new { bless {}, shift } # Not worth having
-
-sub _tt {
+sub template {
     my ($self, $r) = @_;
-    # This bit sucks.
-    my $root = $r->{config}{template_root} || $r->get_template_root;
-    Template->new({ INCLUDE_PATH => [
-        $root,
-        ($r->model_class && File::Spec->catdir($root, $r->model_class->moniker)),
-        File::Spec->catdir($root, "custom"),
-        File::Spec->catdir($root, "factory")
-    ]});
+    my $template = Template->new({ INCLUDE_PATH => [ $self->paths($r) ]});
+    my $output;
+    if ($template->process($r->template, { $self->vars($r) }, \$output)) {
+        $r->{output} = $output;
+        return 1;
+    } else {
+        $r->{error} = $template->error;
+        return 0;
+    }
 }
 
-sub _args {
-    my ($self, $r) = @_;
-    my $class = $r->model_class;
-    my %args = (
-        request => $r,
-        objects => $r->objects,
-        base    => $r->config->{uri_base},
-        config  => $r->config
-        # ...
-    ) ;
-    if ($class) { 
-        $args{classmetadata} = {
-            name => $class,
-            table => $class->table,
-            columns => [ $class->display_columns ],
-            colnames => { $class->column_names },
-            related_accessors => [ $class->related($r) ],
-            moniker => $class->moniker,
-            plural  => $class->plural_moniker,
-            cgi => { $class->to_cgi },
-            description => $class->description
-        };
+1;
 
-        # User-friendliness facility for custom template writers.
-        if (@{$r->objects || []} > 1) { 
-            $args{$r->model_class->plural_moniker} = $r->objects;
-        } else {
-            ($args{$r->model_class->moniker}) = @{$r->objects ||[]};
-        }
-    }
+=head1 NAME
 
-    # Overrides
-    %args = (%args, %{$r->{template_args}||{}});
-    %args;
-}
+Maypole::View::TT - A Template Toolkit view class for Maypole
 
-sub process {
-    my ($self, $r) = @_;
-    my $template = $self->_tt($r);
-    my $output;
-    $template->process($r->template, { $self->_args($r) }, \$output)
-    || return $self->error($r, $template->error);
+=head1 SYNOPSIS
 
-    $r->{content_type} ||= "text/html";
-    $r->{output} = $output;
-    return 200;
-}
+    BeerDB->config->{view} = "Maypole::View::TT"; # The default anyway
 
-sub error {
-    my ($self, $r, $error) = @_;
-    warn $error;
-    if ($error =~ /not found$/) { return -1 }
-    $r->{content_type} = "text/plain";
-    $r->{output} = $error;
-    $r->send_output;
-    exit;
-}
+=head1 DESCRIPTION
 
-1;
+This is the default view class for Maypole; it uses the Template Toolkit
+to fill in templates with the objects produced by Maypole's model classes.
+Please see the Maypole manual, and in particular, the C<View> chapter,
+for the template variables available and for a refresher on how template
+components are resolved.
+
+=head1 AUTHOR
+
+Simon Cozens
+
+=cut
-- 
2.39.5