The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Catalyst-View-Seamstress-2.0
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->{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');
    }

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. You configure the per-request information (e.g. $c->stash->{LOOM} and variables for this template) in your controller.

The meat-skeleton paradigm

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:

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.

Choosing plain-meat or meat-skeleton

There are two items which control how this plugin renders HTML.

  • $c->stash->{LOOM}

    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.

    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.

Tips to View Writers

The order of use base is VERY significant

When your helper module creates MyApp::V::Seamstress it is very important for the use base to look this way:

  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.

Getting config information from MyApp and MyApp::View::*

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::*. $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::*. $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.