NAME
   Dancer::Plugin::DirectoryView - Browse directory contents in Dancer web
   applications

VERSION
   Version 0.01

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 };

       # Calling 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
   If there's just one directory that you want to make accessible, you can
   configure it in the configuration file of your application, under
   "plugins":

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

   If there are more directories, you need to set them up by calling the
   "directory_view" function in your app. The first parameter 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.

 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 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-DirectoryV
   iew>. 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:

   *   RT: CPAN's request tracker

       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Dancer-Plugin-DirectoryVie
       w>

   *   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/>

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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.