NAME Catalyst::View::Seamstress - Seamstress View Class SYNOPSIS # use the helper to create MyApp::View::Seamstress myapp_create.pl view Seamstress Seamstress # edit the comp_root in lib/MyApp/View/Seamstress.pm BEGIN { # IMPORTANT: last character must be "/" $comp_root = "/ernest/dev/catalyst-simpleapp/MyApp/root/"; } # the above is correct assuming your HTML files exist in # /ernest/dev/catalyst-simpleapp/MyApp/root/"; # 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'; $c->forward('MyApp::View::Seamstress'); } # html::hello_world is a Perl package with 2 methods: # - new() # auto-created by spkg.pl in the Seamstress distro # - process() # handwritten by you to rewrite the HTML tree as you need # it was created as follows: metaperl@pool-71-109-151-76:/ernest/dev/catalyst-simpleapp/MyApp/root/html$ cat hello_world.html <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>Hello World</title> </head> <body> <h1>Hello World</h1> <p>Hello, my name is <span id="name">dummy_name</span>. <p>Today's date is <span id="date">dummy_date</span>. </body> </html> metaperl@pool-71-109-151-76:/ernest/dev/catalyst-simpleapp/MyApp/root/html$ metaperl@pool-71-109-151-76:/ernest/dev/catalyst-simpleapp/MyApp/root/html$ spkg.pl --base_pkg=MyApp::View::Seamstress --base_pkg_root=`pwd`/../../lib hello_world.html comp_root........ /ernest/dev/catalyst-simpleapp/MyApp/root/ html_file_path... /ernest/dev/catalyst-simpleapp/MyApp/root/html/ html_file........ hello_world.html html_file sans... hello_world hello_world.html compiled to package html::hello_world metaperl@pool-71-109-151-76:/ernest/dev/catalyst-simpleapp/MyApp/root/html$ # Lets see what html::hello_world looks like. Everything other than # "process()" was auto-generated package html::hello_world; use strict; use warnings; use HTML::TreeBuilder; use lib '/ernest/dev/catalyst-simpleapp/MyApp/root/html/../../lib'; use base qw(MyApp::View::Seamstress); our $tree; sub new { my $file = __PACKAGE__->comp_root() . 'html/hello_world.html' ; -e $file or die "$file does not exist. Therefore cannot load"; $tree =HTML::TreeBuilder->new; $tree->store_declarations; $tree->parse_file($file); $tree->eof; bless $tree, __PACKAGE__; } sub process { my ($self, $c) = @_; $tree->look_down(id => 'name')->replace_content($c->stash->{$_}) for qw(name date); } 1; 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) which looks something like this: package FooBar::View::Seamstress; use strict; use base 'Catalyst::View::Seamstress'; __PACKAGE__->config->{DEBUG} = 'all'; 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::V::Seamstress'); } CONFIGURATION There are a three different ways to configure your view class. The first way is to call the "config()" method in the view subclass. This happens when the module is first loaded. package MyApp::V::Seamstress; use strict; use base 'Catalyst::View::Seamstress'; MyApp::V::Seamstress->config({ comp_root '/absolute/path/to/html/files/' }); The second way is to define a "new()" method in your view subclass. This performs the configuration when the view object is created, shortly after being loaded. Remember to delegate to the base class "new()" method (via "$self->NEXT::new()" in the example below) after performing any configuration. sub new { my $self = shift; $self->config({ comp_root '/absolute/path/to/html/files/' }); return $self->NEXT::new(@_); } The final, and perhaps most direct way, is to define a class item in your main application configuration, again by calling the uniquitous "config()" method. The items in the class hash are added to those already defined by the above two methods. This happens in the base class new() method (which is one reason why you must remember to call it via "NEXT" if you redefine the "new()" method in a subclass). package MyApp; use strict; use Catalyst; MyApp->config({ comp_root '/absolute/path/to/html/files/' }); Note that any configuration items defined by one of the earlier methods will be overwritten by items of the same name provided by the latter methods. RENDERING VIEWS The view plugin renders using the class named in the "template" item in the stash. The items defined in the stash are passed to the Seamstress "process()" method in the same class: 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'); } A "process()" method was shown in the SYNOPSIS. The output generated by the template is stored in "$c->response->output". TEMPLATE PROFILING METHODS new The constructor for the Seamstress view (uses inherited "new"). process eval-requires the module specified in "$c->stash->{template}". Gets the "HTML::Tree" representation of the file via "new" and then calls "process()" to rewrite the tree. Template arguments are $c. Output is stored in "$c->response->body". template_vars Returns a list of keys/values to be used as the variables in the template. "CATALYST_VAR" Allows you to change the name of the Catalyst context object. If set, it will also remove the base and name aliases, so you will have access them through <context>. For example: MyApp->config({ name => 'MyApp', root => MyApp->path_to('root'), 'V::Seamstress' => { CATALYST_VAR => 'Catalyst', }, }); message.tt2: The base is [% Catalyst.req.base %] The name is [% Catalyst.config.name %] "TIMER" If you have configured Catalyst for debug output, and turned on the TIMER setting, "Catalyst::View::Seamstress" will enable profiling of template processing (using Seamstress::Timer). This will embed HTML comments in the output from your templates, such as: <!-- TIMER START: process mainmenu/mainmenu.ttml --> <!-- TIMER START: include mainmenu/cssindex.tt --> <!-- TIMER START: process mainmenu/cssindex.tt --> <!-- TIMER END: process mainmenu/cssindex.tt (0.017279 seconds) --> <!-- TIMER END: include mainmenu/cssindex.tt (0.017401 seconds) --> .... <!-- TIMER END: process mainmenu/footer.tt (0.003016 seconds) --> "TEMPLATE_EXTENSION" a sufix to add when looking for templates bases on the "match" method in Catalyst::Request. For example: package MyApp::C::Test; sub test : Local { .. } Would by default look for a template in <root>/test/test. If you set TEMPLATE_EXTENSION to '.tt', it will look for <root>/test/test.tt. HELPERS The Catalyst::Helper::View::Seamstress and Catalyst::Helper::View::SeamstressSite helper modules are provided to create your view module. There are invoked by the myapp_create.pl script: $ script/myapp_create.pl view Seamstress Seamstress $ script/myapp_create.pl view Seamstress SeamstressSite The Catalyst::Helper::View::Seamstress module creates a basic Seamstress view module. The Catalyst::Helper::View::SeamstressSite module goes a little further. It also creates a default set of templates to get you started. It also configures the view module to locate the templates automatically. SEE ALSO Catalyst, Catalyst::Helper::View::Seamstress, HTML::Seamstress 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.