MojoX::DirectoryListing - show Apache-style directory listings in your Mojolicious app
0.12
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 );
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
public/
public/data-files
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 .
/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
serve_directory_listings( '/research', 'public/files/research/public' ); serve_directory_listings( '/log', '/var/log/system' );
This module exports the "serve_directory_listing" subroutine to the calling package.
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.
$path
public
/data/foo
public/data/foo
The serve_directory_listing function recognizes several options that control the appearance and the behavior of the directory listing.
serve_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.
<N>
<M>
<S>
<T>
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)).
C
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>
<D>
A request that includes the parameter O will override this setting for that request.
O
show-file-time
If true, the directory listing includes the modification time of each file listed. The default is true.
show-file-size
If true, the directory listing includes the size of each file listed. The default is true.
show-file-type
If true, the directory listing includes the MIME type of each file listed. The default is true.
show-forbidden
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
If true, an icon appears to the left of every directory listing indicating the type of file. The default is false.
recursive
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
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.
<style></style>
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.
<body>
<h1>
<hr>
.directory-listing-link
A class that is applied to the <a> tag associated with each filename in the directory listing.
<a>
.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
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.
__DIR__
If a header is not specified, the default header is
<h1 class="directory-listing">Index of __DIR__</h1>
footer
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.
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".
MojoX::DirectoryListing
./public
Marty O'Brien, <mob at cpan.org>
<mob at cpan.org>
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.
bug-mojox-lite-directorylisting at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc MojoX::DirectoryListing
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=MojoX-DirectoryListing
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/MojoX-DirectoryListing
CPAN Ratings
http://cpanratings.perl.org/d/MojoX-DirectoryListing
Search CPAN
http://search.cpan.org/dist/MojoX-DirectoryListing/
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.
Plack::App::Directory
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.
To install MojoX::DirectoryListing, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MojoX::DirectoryListing
CPAN shell
perl -MCPAN -e shell install MojoX::DirectoryListing
For more information on module installation, please visit the detailed CPAN module installation guide.