/ 
Apache-AutoIndex-0.08
River stage zero No dependents
/ Apache::AutoIndex

NAME

Apache::AutoIndex - Perl replacment for mod_autoindex and mod_dir Apache module

SYNOPSIS

PerlModule Apache::Icon
PerlModule Apache::AutoIndex
(PerlModule Image::Magick) optionnal
PerlTransHandler Apache::AutoIndex::transhandler
PerlHandler Apache::AutoIndex

DESCRIPTION

This module can replace completely mod_dir and mod_autoindex standard directory handling modules shipped with apache. It can currently live right on top of those modules, but I suggest simply making a new httpd without these modules compiled-in.

To start using it on your site right away, simply preload Apache::Icon and Apache::AutoIndex either with:

PerlModule Apache::Icon
PerlModule Apache::AutoIndex

in your httpd.conf file or with:

  use Apache::Icon ();
  use Apache::AutoIndex;

in your require.pl file.

Then it's simply adding

PerlTransHandler Apache::Autoindex::transhandler
PerlHandler Apache::AutoIndex

somewhere in your httpd.conf but outside any Location/Directory containers.

VIRTUAL HOSTS

If used in a server using virtual hosts, since mod_perl doesn't have configuration merging routine for virtual hosts, you'll have to put the PerlHandler and PerlTransHandler directives in each and every <VHOST></VHOST> section you wish to use Apache::AutoIndex with.

DIRECTIVES

It uses all of the Configuration Directives defined by mod_dir and mod_autoindex.

Since the documentation about all those directives can be found on the apache website at:

http://www.apache.org/docs/mod/mod_autoindex.html 
http://www.apache.org/docs/mod/mod_dir.html

I will only list modification that might have occured in this perl version.

SUPPORTED DIRECTIVES

  • AddDescription

  • DirectoryIndex

  • FancyIndexing - should use IndexOptions FancyIndexing since 1.3.2

  • IndexOptions - All directives are currently supported. And a few were added

  • HeaderName - It can now accept a list of files instead of just one

  • ReadmeName - It can now accept a list of files instead of just one

  • IndexIgnore

  • IndexOrderDefault

NEW DIRECTIVES

  • IndexOptions

    Thumbnails - Lisitng will now include thumbnails for pictures. Defaults to false.

    ShowPermissions - prints file permissions. Defaults to false.

  • PerlSetVar IndexHtmlBody 'expression'

    This is an expression that should producea complete <BODY> tag when eval'ed. One example could be :

    PerlSetVar IndexHtmlBody '<BODY BACKGROUND=\"$ENV{BACKGROUND}\">'

  • PerlSetVar IndexHtmlTable value

    This is a string that will be inserted inside the table tag of the listing like so : <TABLE $value>

  • PerlSetVar IndexHtmlHead value

    This should be the url (absolute/relative) of a ressource that would be inserted right after the <BODY> tag and before anything else is written.

  • PerlSetVar IndexHtmlFoot value

    This should be the url (absolute/relative) of a ressource that would be inserted right before the </BODY> tag and after everything else is written.

  • PerlSetVar IndexDebug [0|1]

    If set to 1, the listing displayed will print usefull (well, to me) debugging information appended to the bottom. The default is 0.

UNSUPPORTED DIRECTIVES

  • - Hopefully none :-)

THUMBNAILS

Since version 0.07, generation of thumbnails is possible. This means that listing a directory that contains images can be listed with little reduced thumbnails beside each image name instead of the standard 'image' icon.

To enable this you simply need to preload Image::Macick in Apache. The IndexOption option Thumbnails controls thumbnails generation for specific directories like any other IndexOption directive.

USAGE

The way thumbnails are generated/produced can be configured in many ways, but here is a general overview of the procedure.

For each directory containing pictures, there will be a .thumbnails directory in it that will hold the thumbnails. Each time the directory is accessed, and if thumbnail generation is active, small thumbnails will be produced, shown beside each image name, instaed of the normal , generic, image icon.

That can be done in 2 ways. In the case the image is pretty small, no actual thumbnail will be created. Instead the image will be resized with the HEIGHT and WIDTH attributes of the IMG tag.

If the image is big enough, it is resized with Image::Magick and saved in the .thumbnails directory for the next requests.

Change in the configuration of the indexing options will correctly refresh the thumbnails stored. Also if an original image is modified, the thumbnail will be modified accordingly. Still, the browser might screw things up if it preserves the cached images.

The behaviour of the Thumbnail generating code can be customized with these PerlSetVar variables:

DIRECTIVES

  • IndexCacheDir dir

    This is the name of the directory in wich generated thumbnails will be created. Make sure the user under wich the webserver runs has read and write privileges. Defaults to .thumbnails

  • IndexCreateDir 0|1

    Specifies that when a cache directory isn't found, should an attempt to create it be done. Defaults to 1(true), meaning if possible, missing cache directories will be created.

  • ThumbMaxFilesize bytes

    This value fixes the size of an image at wich thumbnail processing isn't even attempted. Since trying to process a few very big images could bring a server down to it's knees. Defaults to 500,000

  • ThumbMinFilesize bytes

    This value fixes the size of an image at wich thumbnail processing isn't actually done. Since trying to process already very small images could would be an overkill, the image is simply resized withe the size attributes of the IMG tag. Defaults to 5,000.

  • ThumbMaxWidth pixels

    This value fixes the x-size of an image at wich thumbnail processing isn't actually done. Since trying to process already very small images could would be an overkill, the image is simply resized withe the size attributes of the IMG tag. Defaults to 4 times the default icon width.

  • ThumbMaxHeight pixels

    This value fixes the y-size of an image at wich thumbnail processing isn't actually done. Since trying to process already very small images could would be an overkill, the image is simply resized withe the size attributes of the IMG tag. Defaults to 4 times the default icon height

  • ThumbScaleWidth scaling-factor

    This value fixes an x-scaling factor between 0 and 1 to resize the images with. The image ratio will be preserved only if there is no scaling factor for the other axis of the image.

  • ThumbScaleHeight scaling-factor

    This value fixes an y-scaling factor between 0 and 1 to resize the images with. The image ratio will be preserved only if there is no scaling factor for the other axis of the image.

  • ThumbWidth pixels

    This value fixes a fixed x-dimension to resize the image with. The image ratio will be preserved only if there is no fixed scaling factor for the other axis of the image. This has no effect if a scaling factor is defined.

  • ThumbHeight pixels

    This value fixes a fixed x-dimension to resize the image with. The image ratio will be preserved only if there is no fixed scaling factor for the other axis of the image. This has no effect if a scaling factor is defined.

TODO

The transhandler problem should be fixed.

Some minor changes to the thumbnails options will still have the thumbnails re-generated. This should be avoided by checking the attributes of the already existing thumbnail.

Some form of garbage collection should be performed or cache directories will fill up.

Find new things to add...

SEE ALSO

perl(1), Apache(3), Apache::Icon(3), Image::Magick(3) .

SUPPORT

Please send any questions or comments to the Apache modperl mailing list <modperl@apache.org> or to me at <gozer@ectoplasm.dyndns.com>

NOTES

This code was made possible by :

Doug MacEachern

<dougm@pobox.com> Creator of Apache::Icon, and of course, mod_perl.

Rob McCool

who produced the final mod_autoindex.c I copied, hrm.., well, translated to perl.

The mod_perl mailing-list

at <modperl@apache.org> for all your mod_perl related problems.

AUTHOR

Philippe M. Chiasson <gozer@ectoplasm.dyndns.com>

COPYRIGHT

Copyright (c) 1999 Philippe M. Chiasson. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.