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';
+ MyApp->config({
+ name => 'MyApp',
+ root => MyApp->path_to('root');,
+ 'V::TT' => {
+ # any TT configurations items go here
+ INCLUDE_PATH => [
+ MyApp->path_to( 'root', 'src' ),
+ MyApp->path_to( 'root', 'lib' ),
+ ],
+ PRE_PROCESS => 'config/main',
+ WRAPPER => 'site/wrapper',
+ TEMPLATE_EXTENSION => '.tt',
- __PACKAGE__->config->{DEBUG} = 'all';
+ # 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');
+ }
+
+ # access variables from template
- 1;
+ The message is: [% message %].
- $c->forward('MyApp::View::TT');
+ # example when CATALYST_VAR is set to 'Catalyst'
+ Context is [% Catalyst %]
+ The base is [% Catalyst.req.base %]
+ The name is [% Catalyst.config.name %]
+
+ # 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. 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.
+ 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';
+
+ MyApp::V::TT->config({
+ INCLUDE_PATH => [
+ MyApp->path_to( 'root', 'templates', 'lib' ),
+ MyApp->path_to( 'root', 'templates', 'src' ),
+ ],
+ 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 => [
+ MyApp->path_to( 'root', 'templates', 'lib' ),
+ MyApp->path_to( 'root', 'templates', 'src' ),
+ ],
+ 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;
+
+ MyApp->config({
+ name => 'MyApp',
+ root => MyApp->path_to('root'),
+ 'V::TT' => {
+ INCLUDE_PATH => [
+ MyApp->path_to( 'root', 'templates', 'lib' ),
+ MyApp->path_to( 'root', 'templates', 'src' ),
+ ],
+ 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.
+
+ DYNAMIC INCLUDE_PATH
+ It is sometimes needed to dynamically add additional paths to the
+ INCLUDE_PATH variable of the template object. This can be done by
+ setting 'additional_include_paths' on stash to a referrence to an array
+ with additional paths:
+
+ $c->stash->{additional_template_paths} = [$c->config->{root} . '/test_include_path'];
+
+ 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 you want to use EVAL perl, add something like this:
+ 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".
- __PACKAGE__->config->{EVAL_PERL} = 1;
- __PACKAGE__->config->{LOAD_TEMPLATES} = undef;
+ 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 %]
+
+ The output generated by the template is stored in
+ "$c->response->output".
+
+ TEMPLATE PROFILING
METHODS
- process
- Renders the template specified in $c->stash->{template} or
- $c->request->match to $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 options as below:
+
+ "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::TT' => {
+ CATALYST_VAR => 'Catalyst',
+ },
+ });
+
+ message.tt2:
+
+ The base is [% Catalyst.req.base %]
+ The name is [% Catalyst.config.name %]
- config
- This allows your view subclass to pass additional settings to the TT
- config hash.
+ "TIMER"
+ If you have configured Catalyst for debug output, and turned on
+ the TIMER setting, "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 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::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
+ 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 / blobdiff