Dancer::Plugin::DirectoryView - Browse directory contents in Dancer web apps
Version 0.02
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); } };
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.
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
url
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:
directories
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
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.
Used to configure multiple directories.
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.
1
template
views/layouts
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.
public
If set to 1, hidden files (with names starting with .) are included in the directory listing.
.
Default: 0
0
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.
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)
layout.tt
listing.tt - The template for the directory listing container (e.g., a table header/footer)
listing.tt
file.tt - The template for a single file in the listing (e.g., a table row)
file.tt
The plugin first looks for this directory in the application's views directory, then in its own views directory.
views
Default: "basic"
"basic"
The URL at which the root directory will be accessible.
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:
system_path
public/files/docs
plugins: DirectoryView: url: /files/docs
or with this call in your application:
directory_view '/files/docs';
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' };
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 };
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 };
Michal Wojciechowski, <odyniec at cpan.org>
<odyniec at cpan.org>
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.
bug-dancer-plugin-directoryview at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Dancer::Plugin::DirectoryView
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Dancer-Plugin-DirectoryView
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Dancer-Plugin-DirectoryView
CPAN Ratings
http://cpanratings.perl.org/d/Dancer-Plugin-DirectoryView
Search CPAN
http://search.cpan.org/dist/Dancer-Plugin-DirectoryView/
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/).
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.
To install Dancer::Plugin::DirectoryView, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dancer::Plugin::DirectoryView
CPAN shell
perl -MCPAN -e shell install Dancer::Plugin::DirectoryView
For more information on module installation, please visit the detailed CPAN module installation guide.