/ 
Catalyst-View-Seamstress-1.10
River stage zero No dependents
/ Catalyst::View::Seamstress

NAME

Catalyst::View::Seamstress - HTML::Seamstress View Class for Catalyst

SYNOPSIS

# 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->{template} = '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');
}

DESCRIPTION

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).

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

CONFIGURATION

The helper app automatically puts the per-application configuration info in MyApp::View::Seamstress.

RENDERING VIEWS

The meat-skeleton paradigm

When Catalyst::View::Seamstress is forwarded to, it can be used in 3 ways depending on how the stash and the View config variables are set at that time.

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.

And Seamstress? Well, here's what you _can_ do:

1 generate the meat, $meat

This is typically what you see in the body part of an HTML page

2 generate the skeleton, $skeleton

This is typically the html, head, and maybe some body

3 put the meat in the skeleton

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.

  • $c->stash->{template}

    The Seamstress view plugin MUST have a template to work on or it will balk with an error:

    sub message : Global {
    my ( $self, $c ) = @_;
    $c->stash->{template} = 'html::hello_world';
    $c->stash->{name}     = 'Billy Bob';
    $c->stash->{date}     = 'medjool sahara';
    $c->forward('MyApp::View::Seamstress');
}

    To be honest, Seamstress does not alter the HTML it unrolls, so the word "template" is really not accurate. But since all the other View classes adopted that place in the stash for the similar thing in Seamstress, we decided to follow suit.

  • MyApp::View::Seamstress->config->{skeleton}

    By default this is not set and the HTML output is simply the result of taking $c->stash->{template}, 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->{template}->fixup() come into effect as described in "The_meat-skeleton_paradigm" in HTML::Seamstress.

    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.

The output generated by the template (and possibly its interaction with a skeleton) is stored in $c->response->body.

new()

The constructor for the Seamstress view

process()

eval-requires the module specified in $c->stash->{template}. Gets the HTML::Tree representation of the file via new and then calls $self->process($c, $c->stash) to rewrite the tree.

NOTE WELL: most views store output in $c->response->body. Seamstress stores it in $c->stash->{woven}.

Tips to View Writers

get config information from MyApp and MyApp::View::Seamstress

assuming Catalyst::View::Seamstress::new() starts off like this:

sub new {
   my $self = shift;
   my $c    = shift;

$self->config contains things set in MyApp::View::Seamstress. $c->config contains things set in MyApp

assuming Catalyst::View::Seamstress::process() starts off similarly:

sub process {
   my ( $self, $c ) = @_;

$self->config contains things set in MyApp::View::Seamstress. $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.

SEE ALSO

Catalyst, Catalyst::View, Catalyst::Helper::View::Seamstress, HTML::Seamstress

A working sample app

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

SUPPORT

Email the author or ping him on #catalyst on irc.perl.org

AUTHORS

Terrence Brannon <metaperl@gmail.com>

COPYRIGHT

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.