/ 
MojoX-DirectoryListing-0.12
River stage zero No dependents
/ MojoX::DirectoryListing

NAME

MojoX::DirectoryListing - show Apache-style directory listings in your Mojolicious app

VERSION

0.12

SYNOPSIS

use Mojolicious;  # or Mojolicious::Lite;
use MojoX::DirectoryListing;

# serve a directory listing under your app's  public/  folder
serve_directory_listing( '/data' );

# serve a directory listing in a different location
serve_directory_listing( '/more-data', '/path/to/other/directory' );

# serve all subdirectories, too
serve_directory_listing( '/data', recursive => 1 );

# change the default display options
serve_directory_listings( '/data', 'show-file-type' => 0, 'show-forbidden' => 1 );

DESCRIPTION

I ported a web application from CGI to Mojolicious. I was mostly pleased with the results, but one of the features I lost in the port was the ability to serve a directory listing. This module is an attempt to make that feature available in Mojolicious, and maybe even make it better.

Mojolicious serves static files under your app's public/ directory. To serve a whole directory under your public/ directory (say, public/data-files), you would call

serve_directory_listings( '/data-files' );

Now a request to your app for /data-files will display a listing of all the files under public/data-files .

To serve a directory listing for a directory that is not under your app's public directory, provide a second argument to serve_directory_listings. For example

serve_directory_listings( '/research', 'public/files/research/public' );
serve_directory_listings( '/log', '/var/log/system' );

EXPORT

This module exports the "serve_directory_listing" subroutine to the calling package.

SUBROUTINES/METHODS

serve_directory_listing

serve_directory_listing( $route, %options )

serve_directory_listing( $route, $path, %options )

Configures the Mojolicious app to serve directory listings for the specified path rom the specified route.

If $path is omitted, then the appropriate directory in your apps public directory will be listed. For example, the route /data/foo will serve a listing for your app's public/data/foo directory.

recognized options

The serve_directory_listing function recognizes several options that control the appearance and the behavior of the directory listing.

sort-column => N | M | S | T

Controls whether the files in a directory will be ordered by <N>ame, file <M>odification time, file <S>ize, or file <T>ype. The default is to order listings by name.

If a request includes the parameter C, it will override this setting for that request. This makes the behavior of this feature similar to the feature in Apache (see http://cpansearch.perl.org/src/MOB/MojoX-DirectoryListing-0.05/ for example [actually, this is an emulation of Apache-style directory listing in Plack)).

display-order => A | D

Controls whether the files will be listed (using the sort criteria from sort-column) in <A>scending or <D>escending order. The default is ascending order.

A request that includes the parameter O will override this setting for that request.

show-file-time => boolean

If true, the directory listing includes the modification time of each file listed. The default is true.

show-file-size => boolean

If true, the directory listing includes the size of each file listed. The default is true.

show-file-type => boolean

If true, the directory listing includes the MIME type of each file listed. The default is true.

show-forbidden => boolean

If true, the directory listing includes files that are not readable by the user running the web server. When such a file is listed, it will not include a link to the file. The default is false.

show-icon => boolean

If true, an icon appears to the left of every directory listing indicating the type of file. The default is false.

recursive => boolean

If true, invoke serve_directory_listing on all subdirectories of the directory being served. The default is false.

For example, to serve all directories as well as all files under your app's public/ folder, it is sufficient to run

serve_directory_listing( '/',  recursive => 1 );
stylesheet => url
stylesheet => \$style-spec

A URL to specify a cascading stylesheet to be applied to the directory listing page, or reference to a scalar that holds style information (suitable for inserting into a pair of <style></style> tags in the output of this subroutine.

If you do wish to override the styles for the directory listing output, the selectors you want to define are:

.directory-listing

A class that is applied to <body>, <h1>, and <hr> elements on the directory listing output.

A class that is applied to the <a> tag associated with each filename in the directory listing.

.directory-listing-header

A class that applies to the column headings (Name, Last Modified, Size, and Type columns) in the directory listing.

.directory-listing-row

A class that applies to a row in the directory listing. which may include a file name, the file's modification time, the file's size, and the file's type.

.directory-listing-name

A class that applies to a filename in the directory listing, but not "forbidden" files -- see .directory-listing-forbidden-name.

.directory-listing-forbidden-name

A class that applies to the filename for a "forbidden" file; that is, a file listing that the user is allowed to see for a file that he/she is not allowed to see. See "show-forbidden".

.directory-listing-time

A class that applies to the display of a file's last modification time in the directory listing.

.directory-listing-size

A class that applies to the display of a file's size in the directory listing.

.directory-listing-type

A class that applies to the display of a file's file type in the directory listing.

If not specified, the default style is the one used by the app-dirserve application (see "ACKNOWLEDGEMENTS").

header => string

Specify HTML code to be included at the top of the directory listing page. If the string contains the token __DIR__, it will be replaced with the path of the directory being requested.

If a header is not specified, the default header is

<h1 class="directory-listing">Index of __DIR__</h1>

Specify HTML code to be included at the bottom of the directory listing page. If the string contains the token __DIR__, it will b e replaced with the path of the directory being requested.

The default footer is the empty string.

set_public_app_dir( $path )

Tells MojoX::DirectoryListing which directory your app uses to serve static data. The default is ./public. The public app dir is used to map the route to an actual path when you don't supply a $path argument to "serve_directory_listing".

AUTHOR

Marty O'Brien, <mob at cpan.org>

BUGS

Please report any bugs or feature requests to bug-mojox-lite-directorylisting at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MojoX-DirectoryListing. 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 MojoX::DirectoryListing

You can also look for information at:

ACKNOWLEDGEMENTS

github user Glenn Hinkle created the app-dirserve microapplication to serve a directory over a webservice. I have borrowed a lot of his ideas and a little of his code in this module.

SEE ALSO

Plack::App::Directory

LICENSE AND COPYRIGHT

Copyright 2013-2021 Marty O'Brien.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.