X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;fp=README;h=3e5f0365951244288e22681f7e0b5a918dc49878;hb=c0eb0527d6a0940639d7d2fc5727c7629385f889;hp=7b94ee1cb8ac1fe9caa112067354cb0299595e12;hpb=94b3529a2770c3143b2f6f96bb75d7b78b7b75cf;p=catagits%2FCatalyst-View-TT.git diff --git a/README b/README index 7b94ee1..3e5f036 100644 --- a/README +++ b/README @@ -2,43 +2,207 @@ NAME 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: + + : + + 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: @@ -50,27 +214,61 @@ DESCRIPTION - 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