view release on metacpan or  search on metacpan

lib/Catalyst/View/TT.pm  view on Meta::CPAN

            INCLUDE_PATH => [
                __PACKAGE__->path_to( 'root', 'templates', 'lib' ),
                __PACKAGE__->path_to( 'root', 'templates', 'src' ),
            ],
        },
    );

You can also configure your view from within your config file if you're
using L<Catalyst::Plugin::ConfigLoader>. This should be reserved for
deployment-specific concerns. For example:

    # MyApp_local.conf (Config::General format)

    <View Web>
      WRAPPER "custom_wrapper"
      INCLUDE_PATH __path_to('root/templates/custom_site')__
      INCLUDE_PATH __path_to('root/templates')__
    </View>

might be used as part of a simple way to deploy different instances of the
same application with different themes.

=head2 DYNAMIC INCLUDE_PATH

Sometimes it is desirable to modify INCLUDE_PATH for your templates at run time.

Additional paths can be added to the start of INCLUDE_PATH via the stash as
follows:

    $c->stash->{additional_template_paths} =
        [$c->config->{root} . '/test_include_path'];

If you need to add paths to the end of INCLUDE_PATH, there is also an
include_path() accessor available:

    push( @{ $c->view('Web')->include_path }, qw/path/ );

Note that if you use include_path() to add extra paths to INCLUDE_PATH, you
MUST check for duplicate paths. Without such checking, the above code will add
"path" to INCLUDE_PATH at every request, causing a memory leak.

A safer approach is to use include_path() to overwrite the array of paths
rather than adding to it. This eliminates both the need to perform duplicate
checking and the chance of a memory leak:

    @{ $c->view('Web')->include_path } = qw/path another_path/;

If you are calling C<render> directly then you can specify dynamic paths by
having a C<additional_template_paths> key with a value of additional directories
to search. See L</CAPTURING TEMPLATE OUTPUT> for an example showing this.

=head2 Unicode (pre Catalyst v5.90080)

B<NOTE> Starting with L<Catalyst> v5.90080 unicode and encoding has been
baked into core, and the default encoding is UTF-8.  The following advice
is for older versions of L<Catalyst>.

Be sure to set C<< ENCODING => 'utf-8' >> and use
L<Catalyst::Plugin::Unicode::Encoding> if you want to use non-ascii
characters (encoded as utf-8) in your templates.  This is only needed if
you actually have UTF8 literals in your templates and the BOM is not
properly set.  Setting encoding here does not magically encode your
template output.  If you are using this version of L<Catalyst> you need
to all the Unicode plugin, or upgrade (preferred)

=head2 Unicode (Catalyst v5.90080+)

This version of L<Catalyst> will automatically encode your body output
to UTF8. This means if your variables contain multibyte characters you don't
need top do anything else to get UTF8 output.  B<However> if your templates
contain UTF8 literals (like, multibyte characters actually in the template
text), then you do need to either set the BOM mark on the template file or
instruct TT to decode the templates at load time via the ENCODING configuration
setting.  Most of the time you can just do:

    MyApp::View::HTML->config(
        ENCODING => 'UTF-8');

and that will just take care of everything.  This configuration setting will
force L<Template> to decode all files correctly, so that when you hit
the finalize_encoding step we can properly encode the body as UTF8.  If you
fail to do this you will get double encoding issues in your output (but again,
only for the UTF8 literals in your actual template text.)

Again, this ENCODING configuration setting only instructs template toolkit
how (and if) to decode the contents of your template files when reading them from
disk.  It has no other effect.

=head2 RENDERING VIEWS

The view plugin renders the template specified in the C<template>
item in the stash.

    sub message : Global {
        my ( $self, $c ) = @_;
        $c->stash->{template} = 'message.tt2';
        $c->forward( $c->view('Web') );
    }

If a stash item isn't defined, then it instead uses the
stringification of the action dispatched to (as defined by $c->action)
in the above example, this would be C<message>, but because the default
is to append '.tt', it would load C<root/message.tt>.

The items defined in the stash are passed to the Template Toolkit for
use as template variables.

    sub default : Private {
        my ( $self, $c ) = @_;
        $c->stash->{template} = 'message.tt2';
        $c->stash->{message}  = 'Hello World!';
        $c->forward( $c->view('Web') );
    }

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<< $c->response->body >>.

=head2 CAPTURING TEMPLATE OUTPUT