/ 
Dancer-Plugin-DirectoryView-0.02
River stage zero No dependents
/ Dancer::Plugin::DirectoryView

NAME

Dancer::Plugin::DirectoryView - Browse directory contents in Dancer web apps

VERSION

Version 0.02

SYNOPSIS

use Dancer::Plugin::DirectoryView;

# Allow browsing of public/files/share
directory_view '/files/share';

# Browse /some/other/directory (located outside of public) as /files/other
directory_view '/files/other' => { root_dir => '/some/other/directory',
                                   system_path => 1 };

# Call directory_view in a route handler
get qr{/files/secret/(.*)} => sub {
    my ($path) = splat;
    
    # Check if the user has permissions to access these files
    if (...) {
        return directory_view(root_dir => '/some/secret/directory',
                              path => $path,
                              system_path => 1);
    }
    else {
        return send_error("Access denied!", 403);
    }
};

DESCRIPTION

Dancer::Plugin::DirectoryView provides an easy way to allow the users of your web application to browse the contents of specific directories on the server. It generates directory index pages to navigate through the directories, in a similar fashion as Apache's mod_autoindex and Plack::App::Directory, but in contrast to those solutions, it does not depend on how your application is deployed.

CONFIGURATION

Put the plugin's settings in the configuration file of your application, under plugins. If there's just one directory that you want to make accessible, set its URL with the url option:

plugins:
    DirectoryView:
        url: /pub/files
        root_dir: /some/directory
        show_hidden_files: 1
        system_path: 1

If you want to configure more than one directory, use the directories option to set a different set of options for each directory:

plugins:
    DirectoryView:
        directories:
            "/pub/files":
                root_dir: /some/directory
                show_hidden_files: 1
                system_path: 1
            "/pub/documents":
                root_dir: /other/directory
                system_path: 1

You can also enable directory browsing by calling the directory_view function in your app. The first parameter passed to the function is a string that defines the URL at which the directory contents will be available, the second is a reference to a hash with options. Example:

directory_view '/pub/photos' => { root_dir => '/home/mike/photos',
                                  system_path => 1 };
                                   
directory_view '/pub/documents' => { root_dir => '/usr/share/doc',
                                     system_path => 1 };

The available configuration options are listed below.

directories

Used to configure multiple directories.

layout

If set to 1, the directory listing is displayed in the application's default layout (instead of the layout defined by the template). If set to a name of a file under views/layouts, that file is used as the layout.

path

The current path to browse/display, relative to root_dir. Required when directory_view is called in a route handler.

root_dir

The root directory which will be available to the users. If it's a relative path, it is assumed to be located under public. It must be specified when directory_view is called in a route handler. If directory_view is called outside a route handler, then root_dir may be omitted, and it will be assumed to be the same as the base URL and relative to public.

show_hidden_files

If set to 1, hidden files (with names starting with .) are included in the directory listing.

Default: 0

system_path

If set to 1, directories and files outside the public directory can be accessed. This is required if root_dir itself is located outside of public.

Default: 0

template

The template to use. It is the name of a directory containing three template files:

  • layout.tt - The layout in which the directory listing is displayed (the HTML document that wraps the listing)

  • listing.tt - The template for the directory listing container (e.g., a table header/footer)

  • file.tt - The template for a single file in the listing (e.g., a table row)

The plugin first looks for this directory in the application's views directory, then in its own views directory.

Default: "basic"

url

The URL at which the root directory will be accessible.

EXAMPLES

Directory under public

In the simplest example, the root directory is located under the public directory of the application, so it's already intended to be world-accessible and you don't have to worry about system_path and permissions. Assuming that the directory is public/files/docs, you can enable it either with the following entries in the configuration file:

plugins:
    DirectoryView:
        url: /files/docs

or with this call in your application:

directory_view '/files/docs';

Directory under public with a different URL

If you want to make the directory accessible, but with a different URL than the system path, provide both the url and the root_dir options in the configuration file:

plugins:
    DirectoryView:
        url: /documents
        root_dir: files/docs

Or, call directory_view like this:

directory_view '/documents' => { root_dir => 'files/docs' };

Directory outside public

When the root directory is located outside of public, you need to enter both the desired url and root_dir, as well as enable the system_path option to allow access to files not within the public directory. Example configuration:

DirectoryView:
    url: /holiday-photos
    root_dir: /home/user/photos/holidays
    system_path: 1

Example call:

directory_view '/holiday-photos' => { root_dir => '/home/user/photos/holidays',
                                      system_path => 1 };

Directory outside public with relative path

Using a relative path in root_dir, you can also access directories above the public directory of your application. For example, if for some reason you would like to let users view your application's logs, you could use this configuration:

plugins:
    DirectoryView:
        url: /logs
        root_dir: ../logs
        system_path: 1

Or this call:

directory_view: '/logs' => { root_dir => '../logs', system_path => 1 };

AUTHOR

Michal Wojciechowski, <odyniec at cpan.org>

BUGS

Please report any bugs or feature requests to bug-dancer-plugin-directoryview at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dancer-Plugin-DirectoryView. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Dancer::Plugin::DirectoryView

You can also look for information at:

ACKNOWLEDGEMENTS

Some parts of the code were heavily inspired by Tatsuhiko Miyagawa's Plack::App::Directory.

Used icons from the Oxygen Icons project (http://www.oxygen-icons.org/).

LICENSE AND COPYRIGHT

Copyright 2011 Michal Wojciechowski.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.