X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=doc%2FView.pod;h=c4691002a3ff36dafb1133454139c55eedb63ab2;hb=4ab33d12a514e0531e16f3d2812b15258de258c5;hp=d2fda7577c84726bc0617f9ea3b84a5de0204935;hpb=c1f02d5a40b94afa2bc1aa54e44b10cde37fccbd;p=maypole.git

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!