NAME

Plack::Middleware::TemplateToolkit - Serve files with Template Toolkit and Plack

SYNOPSIS

use Plack::Builder;

builder {

    # Page to show when requested file is missing
    enable "Plack::Middleware::ErrorDocument",
        404 => "$root/page_not_found.html";

    # These files can be served directly
    enable "Plack::Middleware::Static",
        path => qr{\.[gif|png|jpg|swf|ico|mov|mp3|pdf|js|css]$},
        root => $root;

    enable "Plack::Middleware::TemplateToolkit",
        root => '/path/to/htdocs/', # required
        pass_through => 1; # delegate missing templates to $app

    $app;
}

A minimal .psgi script that uses the middleware as stand-alone application:

use Plack::Middleware::TemplateToolkit;

Plack::Middleware::TemplateToolkit->new( root => "/path/to/docs" );

DESCRIPTION

Enable this middleware or application to allow your Plack-based application to serve files processed through Template Toolkit (TT).

The idea behind this module is to provide access to Template Toolkit (TT) for content that is ALMOST static, but where having the power of TT can make the content easier to manage. You probably only want to use this for the simpliest of sites, but it should be easy enough to migrate to something more significant later.

As Plack::Middleware derives from Plack::Component you can also use this as simple application. If you just want to serve files via Template Toolkit, treat this module as if it was called Plack::App::TemplateToolkit.

By default, the QUERY_STRING params are available to the templates, but the more you use these the harder it could be to migrate later so you might want to look at a propper framework such as Catalyst if you do want to use them:

[% params.get('field') %] params is a L<Hash::MultiValue>

You can mix this middleware with other Plack::App applications and Plack::Middleware which you will find on CPAN.

CONFIGURATIONS

root

Required, root where templates live. This can be an array reference or a string (see Template configuration INCLUDE_PATH)

path

Specifies an URL pattern or a callback to match with requests to serve templates for. See Plack::Middleware::Static for further description. Unlike Plack::Middleware::Static this middleware uses '/' as default path. You may also consider using Plack::App::URLMap and the mount syntax from Plack::Builder to map requests based on a path to this middleware.

extension

Limit to only files with this extension. Requests for other files will result in a 404 response or be passed to the next application if pass_through is set.

content_type

Specify the Content-Type header you want returned. If not specified, the content type will be guessed by Plack::MIME based on the file extension with default_type as default.

default_type

Specify the default Content-Type header. Defaults to to text/html.

vars

Specify a hash reference with template variables or a code reference that gets a Plack::Request objects and returns a hash reference with template variables. By default only the QUERY_STRING params are provided as 'params'.

dir_index

Which file to use as a directory index, defaults to index.html

pass_through

If this option is enabled, requests are passed back to the application, if the incoming request path matches with the path but the requested template file is not found.

pre_process

Optional, supply a file to pre process before serving each html file (see Template configuration PRE_PROCESS)

process

Optional, supply a file to process (see Template configuration PROCESS)

eval_perl

Default to 0, this option lets you run perl blocks in your templates - I would strongly recommend NOT using this. (see Template configuration EVAL_PERL)

interpolate

Default to 0, see Template configuration INTERPOLATE

post_chomp

Defaults to 1, see Template configuration POST_CHOMP

In addition you can specify templates for error codes, for instance:

Plack::Middleware::TemplateToolkit->new(
    root => '/path/to/htdocs/',
    404  => 'page_not_found.html' # = /path/to/htdocs/page_not_found.html
);

If a specified error templates could not be found and processed, an error with HTTP status code 500 is returned, possibly also as template.

METHODS

In addition to the call() method derived from Plack::Middleware, this class defines the following methods for internal use.

process_template($template, $code, \%vars)

Calls the process() method of Template and returns the output in a PSGI response object on success. The first parameter indicates the input template's file name. The second parameter is the HTTP status code to return on success. A reference to a hash with template variables may be passed as third parameter. On failure this method returns an error message instead of a reference.

SEE ALSO

Plack, Template