NAME

Plack::App::Directory::Template - Serve static files from document root with directory index template

VERSION

version 0.27

SYNOPSIS

use Plack::App::Directory::Template;

my $template = "/path/to/templates"; # or \$template_string

my $app = Plack::App::Directory::Template->new(
    root      => "/path/to/htdocs",
    templates => $template, # optional
    filter    => sub {
         # hide hidden files
         $_[0]->name =~ qr{^[^.]|^\.+/$} ? $_[0] : undef;
    }
)->to_app;

DESCRIPTION

Plack::App::Directory::Template extends Plack::App::Directory by support of HTML templates (with Template::Toolkit) for better customization of directory index pages.

CONFIGURATION

root

Document root directory. Defaults to the current directory.

templates

Either a template directory that includes the template file index.html or a template given as string reference.

filter

A code reference that is called for each file before files are passed as template variables One can use such filter to omit selected files and to modify and extend file objects. Note that omitted files are not shown in the directory index but they can still be retrieved.

dir_index

Serve an index file (e.g. "index.html") instead of directory listing if the index file exists.

Template configuration

Template Toolkit configuration options (PRE_PROCESS, POST_CHOMP, PROCESS etc.) are supported as well.

TEMPLATE VARIABLES

The following variables are passed to the directory index template. Have a look at the default template, shipped as file share/index.html with this module, for usage example.

files

List of files, each given as hash reference with the following properties. All directory names end with a slash (/). The special directory ./ is included and ../ as well, unless the root directory is listed.

file.name

Local file name without directory.

file.url

URL path of the file.

file.mime_type

MIME type of the file.

file.stat

File status info as given by File::Stat (dev, ino, mode, nlink, uid, gid, rdev, size, atime, mtime, ctime, blksize, and block).

file.permission

File permissions (given by file.stat.mode & 0777). For instance one can print this in a template with [% file.permission | format("%04o") %].

root

The document root directory as configured (given as absolute path).

dir

The directory that is listed (given as absolute path).

path

The request path (request.path).

request

Information about the HTTP request as given by Plack::Request. Includes the properties parameters, base, scheme, path, and user.

The following example should clarify the meaning of several template variables. Given a Plack::App::Directory::Template to list directory /var/files, mounted at URL path /mnt/:

builder {
    mount '/mnt/'
        => Plack::App::Directory::Template->new( root => '/var/files' );
    ...
}

The request http://example.com/mnt/sub/ to subdirectory would result in the following template variables (given a file named #foo.txt in this directory):

[% root %]       /var/files
[% dir %]        /var/files/sub
[% path %]       /sub/
[% urlpath %]    /mnt/sub/

[% file.name %]  #foo.txt
[% file.url %]   /mnt/sub/%23foo.txt

Try also Plack::Middleware::Debug::TemplateToolkit to inspect template variables for debugging.

METHODS

template_vars( %vars )

This method is internally used to construct a hash reference with template variables. The constructed hash must contain at least the files array. The method can be used as hook in subclasses to modify and extend template variables.

SEE ALSO

Plack::App::Directory, Plack::Middleware::TemplateToolkit

AUTHOR

Jakob Voß

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Jakob Voß.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.