Catalyst::View::TT - Template View Class
SYNOPSIS
- # use the helper
- create.pl view TT TT
+ # use the helper to create View myapp_create.pl view TT TT
- # lib/MyApp/View/TT.pm
- package MyApp::View::TT;
+ # configure in lib/MyApp.pm
- use base 'Catalyst::View::TT';
+ our $ROOT = '/home/dent/catalyst/MyApp';
- __PACKAGE__->config->{DEBUG} = 'all';
+ MyApp->config({
+ name => 'MyApp',
+ root => $ROOT,
+ 'MyApp::V::TT' => {
+ # any TT configurations items go here
+ INCLUDE_PATH => [
+ "$ROOT/templates/src",
+ "$ROOT/templates/lib"
+ ],
+ PRE_PROCESS => 'config/main',
+ WRAPPER => 'site/wrapper',
+
+ # two optional config items
+ CATALYST_VAR => 'Catalyst',
+ TIMER => 1,
+ },
+ });
+
+ # render view from lib/MyApp.pm or lib/MyApp::C::SomeController.pm
+
+ sub message : Global {
+ my ( $self, $c ) = @_;
+ $c->stash->{template} = 'message.tt2';
+ $c->stash->{message} = 'Hello World!';
+ $c->forward('MyApp::V::TT');
+ }
- 1;
+ # access variables from template
+
+ The message is: [% message %].
+
+ # example when CATALYST_VAR is set to 'Catalyst'
+ Context is [% Catalyst %]
+ The base is [% Catalyst.req.base %]
+ The name is [% Catalyst.config.name %]
- # Meanwhile, maybe in an '!end' action
- $c->forward('MyApp::View::TT');
+ # example when CATALYST_VAR isn't set
+ Context is [% c %]
+ The base is [% base %]
+ The name is [% name %]
DESCRIPTION
- This is the "Template" view class. Your subclass should inherit from
- this class. The plugin renders the template specified in
- "$c->stash->{template}" or "$c->request->match". The template variables
- are set up from the contents of "$c->stash", augmented with "base" set
- to "$c->req->base", "c" to $c and "name" to "$c->config->{name}". The
- output is stored in "$c->response->output".
+ This is the Catalyst view class for the Template Toolkit. Your
+ application should defined 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 TT TT
+
+ This creates a MyApp::V::TT.pm module in the lib directory (again,
+ replacing "MyApp" with the name of your application) which looks
+ something like this:
+
+ package FooBar::V::TT;
+
+ use strict;
+ use base 'Catalyst::View::TT';
+
+ __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 TT view class.
+
+ # In MyApp or MyApp::Controller::SomeController
+
+ sub end : Private {
+ my( $self, $c ) = @_;
+ $c->forward('MyApp::V::TT');
+ }
+
+ 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::TT;
+
+ use strict;
+ use base 'Catalyst::View::TT';
+
+ our $ROOT = '/home/dent/catalyst/MyApp';
+
+ MyApp::V::TT->config({
+ INCLUDE_PATH => ["$ROOT/templates/src", "$ROOT/templates/lib"],
+ PRE_PROCESS => 'config/main',
+ WRAPPER => 'site/wrapper',
+ });
+
+ 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({
+ INCLUDE_PATH => ["$ROOT/templates/src", "$ROOT/templates/lib"],
+ PRE_PROCESS => 'config/main',
+ WRAPPER => 'site/wrapper',
+ });
+ 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;
+
+ our $ROOT = '/home/dent/catalyst/MyApp';
+
+ MyApp->config({
+ name => 'MyApp',
+ root => $ROOT,
+ 'MyApp::V::TT' => {
+ INCLUDE_PATH => ["$ROOT/templates/src", "$ROOT/templates/lib"],
+ PRE_PROCESS => 'config/main',
+ WRAPPER => 'site/wrapper',
+ },
+ });
+
+ 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 the template specified in the "template" item in
+ the stash.
+
+ sub message : Global {
+ my ( $self, $c ) = @_;
+ $c->stash->{template} = 'message.tt2';
+ $c->forward('MyApp::V::TT');
+ }
+
+ If a class item isn't defined, then it instead uses the current match,
+ as returned by "$c->match". In the above example, this would be
+ "message".
+
+ The items defined in the stash are passed to the Template Toolkit for
+ use as template variables.
+
+ sub message : Global { sub default : Private { my ( $self, $c ) = @_;
+ $c->stash->{template} = 'message.tt2'; $c->stash->{message} = 'Hello
+ World!'; $c->forward('MyApp::V::TT'); }
+
+ A number of other template variables are also added:
+
+ c A reference to the context object, $c
+ base The URL base, from $c->req->base()
+ name The application name, from $c->config->{ name }
+
+ These can be accessed from the template in the usual way:
+
+ <message.tt2>:
+
+ The message is: [% message %]
+ The base is [% base %]
+ The name is [% name %]
- If you want to override TT config settings, you can do it there by
- setting "__PACKAGE__->config->{OPTION}" as shown in the synopsis. Of
- interest might be "EVAL_PERL", which is disabled by default, and
- "LOAD_TEMPLATES", which is set to use the provider.
+ If you prefer, you can set the "CATALYST_VAR" configuration item to
+ define the name of a template variable through which the context can be
+ referenced.
- If you want to use EVAL perl, add something like this:
+ MyApp->config({
+ name => 'MyApp',
+ root => $ROOT,
+ 'MyApp::V::TT' => {
+ CATALYST_VAR => 'Catalyst',
+ },
+ });
- __PACKAGE__->config->{EVAL_PERL} = 1;
- __PACKAGE__->config->{LOAD_TEMPLATES} = undef;
+ message.tt2:
- If you have configured Catalyst for debug output "Catalyst::View::TT"
- will enable profiling of template processing (using "Template::Timer".
- This will cause HTML comments will get embedded in the output from your
- templates, such as:
+ The base is [% Catalyst.req.base %]
+ The name is [% Catalyst.config.name %]
+
+ The output generated by the template is stored in
+ "$c->response->output".
+
+ TEMPLATE PROFILING
+ If you have configured Catalyst for debug output, "Catalyst::View::TT"
+ will enable profiling of template processing (using Template::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 END: process mainmenu/footer.tt (0.003016 seconds) -->
- You can supress template profiling when debug is enabled by setting:
+ You can suppress template profiling by setting the "TIMER" configuration
+ item to a false value.
- __PACKAGE__->config->{CONTEXT} = undef;
+ MyApp->config({
+ 'MyApp::V::TT' => {
+ TIMER => 0,
+ },
+ });
METHODS
- process
- Renders the template specified in "$c->stash->{template}" or
- "$c->request->match". Template variables are set up from the contents of
- "$c->stash", augmented with "base" set to "$c->req->base", "c" to $c and
- "name" to "$c->config->{name}". Output is stored in
- "$c->response->output".
+ new The constructor for the TT view. Sets up the template provider, and
+ reads the application config.
+
+ process
+ Renders the template specified in "$c->stash->{template}" or
+ "$c->request->match". Template variables are set up from the
+ contents of "$c->stash", augmented with "base" set to
+ "$c->req->base", "c" to $c and "name" to "$c->config->{name}".
+ Alternately, the "CATALYST_VAR" configuration item can be defined to
+ specify the name of a template variable through which the context
+ reference ($c) can be accessed. In this case, the "c", "base" and
+ "name" variables are omitted. Output is stored in
+ "$c->response->output".
+
+ config
+ This method allows your view subclass to pass additional settings to
+ the TT configuration hash, or to set the "CATALYST_VAR" and "TIMER"
+ options.
- config
- This allows your view subclass to pass additional settings to the TT
- config hash.
+ HELPERS
+ The Catalyst::Helper::View::TT and Catalyst::Helper::View::TTSite helper
+ modules are provided to create your view module. There are invoked by
+ the myapp_create.pl script:
+
+ $ script/myapp_create.pl view TT TT
+
+ $ script/myapp_create.pl view TT TTSite
+
+ The Catalyst::Helper::View::TT module creates a basic TT view module.
+ The Catalyst::Helper::View::TTSite 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, Catalyst::Helper::View::TT, Catalyst::Helper::View::TTSite,
+ Template::Manual
+
+AUTHORS
+ Sebastian Riedel, "sri@cpan.org"
+
+ Marcus Ramberg, "mramberg@cpan.org"
+
+ Jesse Sheidlower, "jester@panix.com"
-AUTHOR
- Sebastian Riedel, "sri@cpan.org" Marcus Ramberg, "mramberg@cpan.org"
+ Andy Wardley, "abw@cpan.org"
COPYRIGHT
This program is free software, you can redistribute it and/or modify it
projects / catagits/Catalyst-View-TT.git / commitdiff