Catalyst::View::Seamstress - HTML::Seamstress View Class for Catalyst
# use the helper to create MyApp::View::Seamstress # where comp_root and skeleton are optional
myapp_create.pl view Seamstress Seamstress /path/to/html html::skeleton ^-modulenm ^-helpernm ^-comp_root ^-skeleton
# optionally edit the skeleton and meat_pack routines # in lib/MyApp/View/Seamstress.pm
# render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
sub message : Global { my ( $self, $c ) = @_; $c->stash->{LOOM} = 'html::hello_world'; $c->stash->{name} = 'Mister GreenJeans'; $c->stash->{date} = 'Today'; # the DefaultEnd plugin would mean no need for this line $c->forward('MyApp::View::Seamstress'); }
This is the Catalyst view class for HTML::Seamstress. Your application should define a view class which is a subclass of this module. The easiest way to achieve this is using the myapp_create.pl script (where myapp should be replaced with whatever your application is called). This script is created as part of the Catalyst setup.
$ script/myapp_create.pl view Seamstress Seamstress
This creates a MyApp::View::Seamstress.pm module in the lib directory (again, replacing MyApp with the name of your application).
MyApp
Now you can modify your action handlers in the main application and/or controllers to forward to your view class. You might choose to do this in the end() method, for example, to automatically forward all actions to the Seamstress view class.
# In MyApp or MyApp::Controller::SomeController sub end : Private { my( $self, $c ) = @_; $c->forward('MyApp::View::Seamstress'); }
Or you might like to use Catalyst::Plugin::DefaultEnd
The helper app automatically puts the per-application configuration info in MyApp::View::Seamstress. You configure the per-request information (e.g. $c->stash->{LOOM} and variables for this template) in your controller.
MyApp::View::Seamstress
$c->stash->{LOOM}
When Catalyst::View::Seamstress is forwarded to, it will operate in one of 2 ways: a plain meat way or a meat-skeleton way. Plain meat is simple: the View takes $c->stash->{template} and calls new() and process() on it and stores the result in $c->response->body. Meat-skeleton is designed to facilitate the way that web sites are typically designed. It's discussion follows:
$c->stash->{template}
new()
process()
$c->response->body
HTML pages typically have meat and a skeleton. The meat varies from page to page while the skeleton is fairly (though not completely) static. For example, the skeleton of a webpage is usually a header, a footer, and a navbar. The meat is what shows up when you click on a link on the page somewhere. While the meat will change with each click, the skeleton is rather static.
The perfect example of
Mason accomodates the meat-skeleton paradigm via an autohandler and $m->call_next(). Template accomodates it via its WRAPPER directive.
autohandler
$m->call_next()
WRAPPER
And Seamstress? Well, here's what you _can_ do:
$meat
This is typically what you see in the body part of an HTML page
body
$skeleton
This is typically the html, head, and maybe some body
So, nothing about this is forced. This is just how I typically do things and that is why Catalyst::View::Seamstress has support for this.
There are two items which control how this plugin renders HTML.
The Seamstress view plugin MUST have a LOOM to work on or it will balk with an error:
sub message : Global { my ( $self, $c ) = @_; $c->stash->{LOOM} = 'html::hello_world'; $c->stash->{name} = 'Billy Bob'; $c->stash->{date} = 'medjool sahara'; $c->forward('MyApp::View::Seamstress'); }
MyApp::View::Seamstress->config->{skeleton}
By default this is not set and the HTML output is simply the result of taking $c->stash->{LOOM}, calling new() to create an HTML tree and then passing this to process() so that it can rework the tree.
However, if MyApp::View::Seamstress->config->{skeleton} is set, then both its value and the values of MyApp::View::Seamstress->config->{meat_pack} and $stash->{LOOM}->fixup() come into effect as described in "The_meat-skeleton_paradigm" in HTML::Seamstress.
MyApp::View::Seamstress->config->{meat_pack}
$stash->{LOOM}->fixup()
Let's take that a little slower: $stash->{template}->fixup() means: given a Seamstress-style Perl class, whose name is $stash->{template}, call the method fixup() in that class so that it can do a final fixup of the entire HTML that is about to be shipped back to the client.
$stash->{template}->fixup()
$stash->{template}
fixup()
The output generated by the template (and possibly its interaction with a skeleton) is stored in $c->response->body.
When your helper module creates MyApp::V::Seamstress it is very important for the use base to look this way:
MyApp::V::Seamstress
use base
use base qw(Catalyst::View::Seamstress HTML::Seamstress );
and not this way:
use base qw(HTML::Seamstress Catalyst::View::Seamstress );
so that certain calls (probably new) get handled properly.
assuming Catalyst::View::Seamstress::new() starts off like this:
Catalyst::View::Seamstress::new()
sub new { my $self = shift; my $c = shift;
$self->config contains things set in MyApp::View::*. $c->config contains things set in MyApp
$self->config
MyApp::View::*
$c->config
assuming Catalyst::View::Seamstress::process() starts off similarly:
Catalyst::View::Seamstress::process()
sub process { my ( $self, $c ) = @_;
$self->config contains things set in MyApp::View::*. $c->config contains things set in MyApp.
There is no automatic merging of the two sources of configuration: you have to do that yourself if you want to do it.
Catalyst, Catalyst::View, Catalyst::Helper::View::Seamstress, HTML::Seamstress
The best way to see a fully working Seamstress-style Perl class is to pull down the working sample app from sourceforge.
A working sample app, which does both simple and meat-skeleton rendering is available from Sourceforge CVS:
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/seamstress login cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/seamstress co -P catalyst-simpleapp
Email the author or ping him on #catalyst on irc.perl.org
#catalyst
irc.perl.org
Terrence Brannon <metaperl@gmail.com>
This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
To install Catalyst::View::Seamstress, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Catalyst::View::Seamstress
CPAN shell
perl -MCPAN -e shell install Catalyst::View::Seamstress
For more information on module installation, please visit the detailed CPAN module installation guide.