/ 
App-Rad-Plugin-TT-0.2
River stage zero No dependents
/ App::Rad::Plugin::TT

NAME

App::Rad::Plugin::TT - Template Toolkit extension for the App::Rad framework

SYNOPSIS

use App::Rad qw(TT);
App::Rad->run();

sub mycommand {
    my $c = shift;

    # ...
    $c->stash->{template} = 'mytemplate.tt2';
    return $c->process();
}

You can also customize your template configurations during setup:

sub setup {
    my $c = shift;
    $c->register_commands();  # or whatever

    $c->tt_config({
            # any TT configuration items go here
            INCLUDE_PATH    => '/some/template/path',
            PRE_PROCESS     => 'myapp/main',
            WRAPPER         => 'some/wrapper',

            # plus some additional goodness :)
            CONTROLLER_VAR     => 'c',
            TEMPLATE_EXTENSION => '.tt2',
    });
}

DESCRIPTION

This module extends App::Rad's functionality by letting you use Template Toolkit to render your output (or anything you like).

Rendering Output

When you call $c->process() from inside your App::Rad commands, it will try to render whatever template file is specified in the 'template' stash variable. If the stash item isn't defined, it will instead look for a template file with the same name as the command (appended, by default, with the '.tt2' extension).

While processing, all the items defined in the stash are passed to the Template Toolkit for use as template variables. This means that, if you have:

$c->stash->{foo} = 1;
$c->stash->{bar} = 2;
$c->stash->{baz} = 3;

they can be directly accessed as:

[% foo %]
[% bar %]
[% baz %]

The $c context object is also passed to the template as the 'c' variable, should you need to use any other values:

[% c.config.someconfig %]
[% c.argv %]

Also, please note that, if you happen to have a stash variable named 'c', it will only be accessible through [% c.stash.c %].

Capturing Template Output

Keep in mind that, although you will probably just want to return() the processed template from your command, you don't actually have to. You can just as easily use the output of the template for some purpose other than displaying in the response, such as sending an email, or writing to a file.

Post-processing Output

App::Rad has a special function called post_process() that actually prints whatever is returned from your commands. While using templates, you have usually two different approaches:

  • Render the template from inside your commands, and return that rendered value. This will store the output inside $c->output for the post_process() function to handle. By default, it just prints that output appended with a newline, and this is most likely what you want for simple usage.

  • Set the template inside your commands, don't render it, and return nothing. This way you can render any received template from inside your custom post_process() function, in a way that will let you normalize data before rendering or whatever, providing much more flexibility.

Either way, it's just fine :)

METHODS

process()

Returns the rendered template specified in $c->stash->{template}, or a Template::Exception object upon error. If there is no template variable set, it will look for a template with the same name as the command in which the method call resides. For example:

sub something {
    my $c = shift;
    return $c->process();
}

Since no 'template' variable was set in the stash, it will automatically render a template called 'something', inside the template directories set via the INCLUDE_PATH configuration variable. Please refer to the TEMPLATE_EXTENSION variable below for more information on how to add a default file suffix for your templates.

process_array()

use_tt_post_process()

no_tt_post_process()

tt_config()

This method lets you setup Template Tookit as you see fit for your application. It receives a hash reference where you can put *any* TT configuration items. Please refer to Template::Config for more information on accepted options. Although you can call this method anywhere in your code, developers are advised to do it inside App::Rad's setup() special function.

Note that you don't have to actually call this method at all for the plugin to work. If you don't, App::Rad::Plugin::TT will fall to the default configuration values. This is simply a helper method for people with more complex templating needs.

Besides the standard TT configuration explained above, you can also setup the following plugin variables:

CONTROLLER_VAR

Allows you to change the name of App::Rad's context object, as seen from inside the template. For example:

$c->tt_config({
        CONTROLLER_VAR => 'Rad',  # default value is 'c', just like in App::Rad
});

Then, later on your command:

$c->stash->{template} = 'message.tt2';
$c->stash->{message}  = 'Hello, World!';
return $c->process();

Then your message.tt2 template could be something like this:

The message is [% message %]

[% FOREACH arg IN Rad.argv %]
   Argument [% arg %] was typed!
[% DONE %]

TEMPLATE_EXTENSION

A filename suffix to add when looking for templates, either while trying to match them to your command name or if you ommit it from the 'template' stash variable. For example, if you set TEMPLATE_EXTENSION to '.tt2', then:

$c->stash->{template} = 'whatever';

will search for the file 'whatever' and 'whatever.tt2'. However, if you do:

$c->stash->{template} = 'whatever.tt2';

then it will only search for 'whatever.tt2'.

Also, if you don't specify a template variable on your stash, then something like:

sub mycmd {
    my $c = shift;
    return $c->process();
}

would by default look for something called <rootdir>/mycmd. If you set TEMPLATE_EXTENSION to '.tt2', it will look for <rootdir>/mycmd.tt2.

SEE ALSO

App::Rad, Template

AUTHORS

Fernando Correa de Oliveira, <fco at cpan.org> Breno G. de Oliveira, <garu at cpan.org>

COPYRIGHT

This program is free software, you can redistribute it and/or modify it under the same terms as Perl 5 itself.