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]$},
            INCLUDE_PATH => $root;

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

        $app;
    }

A minimal .psgi script as stand-alone application:

    use Plack::Middleware::TemplateToolkit;

    Plack::Middleware::TemplateToolkit->new( INCLUDE_PATH => "/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 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.

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

This middleware reads and sets the PSGI environment variable tt.vars for variables passed to templates. 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>

CONFIGURATIONS

You can use all configuration options that are supported by Template Toolkit (INCLUDE_PATH, INTERPOLATE, POST_COMP...). See Template::Manual::Config for an overview. The only mandatory option is INCLUDE_PATH to point to where the templates live.

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'. Templates variables specified by this option are added to existing template variables in the tt.vars environment variable.

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. Disabled by default, so all matching requests result in a valid response with status code 200, 404, or 500.

tt

Directly set an instance of Template instead of creating a new one:

  Plack::Middleware::TemplateToolkit->new( %tt_options );

  # is equivalent to:

  my $tt = Template->new( %tt_options );
  Plack::Middleware::TemplateToolkit->new( tt => $tt );

utf8_allow

PSGI expects the content body to be a byte stream, but Template Toolkit is best used with templates and variables as UTF8 strings. For this reason processed templates are encoded to UTF8 byte streams unless you enable this options. It is then up to you to ensure that only byte streams are emitted by your PSGI application. It is recommended to use Plack::Middleware::Lint and test with Unicode characters or your application will likely fail.

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

  Plack::Middleware::TemplateToolkit->new(
      INCLUDE_PATH => '/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.

process_error ( $code, $error, $type, $req ) = @_;

Returns a PSGI response to be used as error message. Error templates are used if they have been specified and prepare_app has been called before. This method tries hard not to fail: undefined parameters are replaced by default values.

SEE ALSO

Plack, Template

AUTHORS

Leo Lapworth (started) and Jakob Voss (most of the work!)