DirWrap Photo User Documentation

General Information

DirWrap Photo is a CGI script written in PERL that takes the contents of a specified directory and wraps it in an html template of your choice. It is a variation of DirWrap that automatically generates thumbnails of JPEG type images. It was written primarily to provide a means for outputting directory contents on web servers that are configured to disallow directory listings via URL but it can be used with any web server that allows CGI scripts to be run.

It's advantages include the ability to "hide" files so that they do not show up in the directory listing, the ability to exclude specific directories from display, and the ability to alter the look and feel of the output by utilizing different templates for different directories.

Calling the script via CGI results in a listing of hyperlinked file and directory names wrapped in html code specified in a user created template. File details include the file size and last modified date. Directories are differentiated with a small folder icon. New files can be identified graphically by user set parameters. Files can be sorted in a variety of fashions.

DirWrap Photo generates thumbnails that are proportional to the original image and sized according to a user specified parameter. A check is made to see if a thumbnail exists for a given image and if the thumbnail doesn't exist it is created on the fly.

DirWrap Photo has been verified to work on the following configurations:

• PERL

  • 5.0x
  • ActivePerl 5.6.1

• OS and Webserver

  • Unix/Linux running Apache 1.3.x
  • Solaris running Zues
  • Windows 2000 running Apache 1.3.2
  • Unix/Solaris running iPlanet

If you have DirWrap Photo up and running on another platform please let us know so that we can update this list.

Donations

DirWrap Photo is free software in both the license and monetary senses. However, if you like the script and/or find it useful and would like to show your appreciation in recognition of that fact, you can make a donation using by clicking the graphic below:

Revision History

Installing DirWrap Photo

Installation is pretty simple.

1. Download the script.

2. Decompress it using the software of your choice.

3. Upload the dirwrap_photo.cgi file to the desired directory on your webserver. The file should be uploaded as ascii text.

4. Set the file permissions to allow the server to execute the script. Generally speaking, you should set the permissions to the most restrictive that you can get away with. If you are not using a wrapper script (such as cgiwrap), or a directory that allows you to execute the script as the owner, you will probably have to set the permission so that Owner, Group, and Other can read and execute the file. The easiest way to do this is to execute the command chmod 755 dirwrap_photo.cgi once the file has been uploaded to the server.

5. Upload your templates to the directory you wish to store them in. It is recommended to store the templates in the same directory as dirwrap_photo.cgi, but they should work anywhere you want to put them as long as you supply the correct absolute path in the script configuration.

6. Set the file permission for the templates. The templates do not need to be executable but the do need to be readable by the server. The easiest way to do this is to execute the command chmod 744 templatename.html on each template file once they have been uploaded to the server.

7. Upload the image files to the directory of your choice. This directory can be your standard image directory if you have one or any other directory that can be accessed via URL.

Configuration

Configuration of DirWrap Photo is done through modify the information found in the config.txt file. Configuration is divided into the following sections:

• Variables For Your System
• Security Parms
• Customization
• Table Row/Entry Formatting
• Normal Mode Table Formatting
• Album Mode Table Formatting
• Download Counter Parms
• File Upload Utility Parms
• Thumbnail Parms
• Album Mode Parms
• Icon Associations
• Error Messages

• Variables For Your System

  The following script variables must be set correctly for the script to run properly. The most common error made in this part of the configuration is confusing URLs with absolute paths.
  • PERL path - The first line of the script must be changed to reflect the proper path to PERL on your web server unless, of course, your PERL path matches the default of "#!/usr/local/bin/perl". NOTE: This is the only part of the configuration that is not located in the config.txt. file.

  • $ENV{'PATH'}; - List of valid paths PERL should use to find modules etc. This parameter is needed to untaint the environment path for security reasons. The default value is '/usr/lib'. This should be sufficient for most PERL installations but you may need to add additional path info here. If you experience errors indicating that a module could not be found consult your hosting support to find out what additional paths you should add here. Separate each path you wan to include with a ":" as in the example below.

    Example: $ENV{'PATH'} = '/bin:/usr/bin:/usr/lib';

  • $admin_email - The email address you want admin emails to be sent to. Use single quotes on this parameter to avoid problems with PERL interpreting the "@" as an array.

    Example: $admin_email = 'your_email@your.com';

  • $base_path - This parameter should be set to the absolute file path (not URL) to your starting directory. INCLUDE the leading and trailing "/".

    Example: $base_path = "/home/username/www/";

  • $templates - This parameter should be set to the absolute path (not URL) to the directory that will hold your templates. INCLUDE the leading and trailing "/".

    Example: $templates = "/home/username/www/path/cgi-bin/dirwrap";

  • $base_url - The main URL to your web site. This is used to create the links for the displayed filenames. It should be the URL that corresponds to the absolute path defined in $base_path above. You must INCLUDE the trailing "/".

    Example: $base_url = "http://www.your.domain/";

  • $dirwrap_url - The URL to the DirWrap Photo script. This URL should be relative to $base_url above. You must INCLUDE the leading "/".

    Example: $dirwrap_url = "/cgi-bin/dirwrap/dirwrap_photo.cgi";

  • $image_url - The URL to the DirWrap Photo images. DO NOT include the trailing "/".

    Example: $image_url = "http://www.your.domain/images";

  • $default_template - Sets the default template to use if none is specified in the DirWrap Photo call. As with all template names, DO NOT INCLUDE the .html.

    Example: $default_template = "example";

  • $default_sort - Determines the default sort option to be used if no sort option is specified in the DirWrap Photo call.

    Example: $default_sort = "by_r_date";

    Note: The $default_sort option only affects files. Directories are always sorted by name.

    Possible values:

    • by_name: Files are sorted based on the file name in ascending order
    • by_r_name: Files are sorted based on the file name in descending order
    • by_size: Files are sorted by size in ascending order
    • by_r_size: Files are sorted by size in descending order
    • by_date: Files are sorted by last modified date in ascending order
    • by_r_date: Files are sorted by last modified date in descending order
    • by_count: Files are sorted by download count in ascending order
    • by_r_count: Files are sorted by download count in descending order

    Example: $default_sort = "by_r_size";

  • $sendmail_location - Path and options to sendmail or its equivalent on your server. Consult your hosting service for the proper value for this parameter.

    Example: $sendmail_location = '/usr/bin/sendmail -t';

   

• Security Parms

  • $admin_code - The password that allows access to the admin functions of the script. Can be an alpha numeric value of any length and is case sensitive. BE SURE TO CHANGE THIS VALUE FROM THE DEFAULT!

    Example: $admin_code = "admin";

  • $allow_dirwrap_links - This parameter determines whether or not to allow DirWrap Photo to create DirWrap Photo calls for directory links.

    If the value is set to yes, DirWrap Photo will link directory names with standard DirWrap Photo call syntax. This eliminates the need to have an index file in each directory. This will also make your calls to DirWrap Photo visible to users through this link. If set to any other value, DirWrap Photo will generate a simple link to the directory. This essentially means that you must include an index file with an SSI call in the directory being linked to have the contents of the directory DirWrapped.

    NOTE: This parameter will not hide DirWrap Photo calls for files if you are using the download counter or if the wrap photos option is on. If you want to totally hide all DirWrap Photo calls you cannot use either of these functions.

    Example: $allow_dirwrap_links = "yes";

  • $allow_path_parm - This parameter determines whether or not to allow a "path" parameter to be passed in the DirWrap Call.

    If set to "no" the path parm in the dirwrap call (path=some/path) will not be allowed. Setting this parm to "no" forces you to use SSI via an index file in the directory you wish to list. If set to "yes" you will be able to include a path parm in the dirwrap call.

    If you are attempting to use server authentication to allow only certain groups to access certain directories you should set this to "no". Otherwise, savvy users could bypass the server authentication by supplying a specific path.

    If you are not trying to use server authentication to allow only certain groups to access certain directories and you are not using SSI via an index file in the directory, leave this parm set to "yes"

    Example: $allow_path_parm= "yes";

  • @hidedirs - This array represents the list of path and directory values that will be rejected by DirWrap Photo. Names and paths must be complete. At a minimum you should probably have your "cgi-bin" listed in this array.

    Example: @hidedirs = ("cgi-bin", "images", "thumbnails", "somedir/someotherdir");

  • $show_hidden_files - If set to "yes", allows UNIX hidden files (files that start with ".") to be displayed. It's recommended to set this to "no". If set to "no" it is not necessary to list hidden files in the @hidefiles array.

    Example: $show_hidden_files = "no";

  • @hidefiles - This array represents the list of file or directory names that will not be shown in the resulting output of the DirWrap Photo script. Names must be complete and include extensions. Typical contents would be "cgi-bin" for obvious security reasons, and your index file to help prevent confusion.

    Example: @hidefiles = ("index.shtml", "index.html", "cgi-bin");

  • @hideexts - This array represents the list of files to hide by extension. Files with the listed extensions will not be displayed. Do not include the "." in the extension. This is assumed.

    This parameter has two special values:

    • none - hides all files that do not have an extension
    • dir - hides all directories

    Example: @hideexts = ("html", "txt", "dll", "none");

  • $send_admin_email - If set to "yes" an email will be sent to the email address defined by $admin_email whenever any of the following events occur:
    • An error message is received.
    • A new file is uploaded using the file upload utility
    • A directory is created using the file upload utility
    • A file/directory is deleted using the file upload utility
    • Any counts file admin function is performed (reset, delete, cleanup)

    Included in the email will be the error message or appropriate file information for the action performed, and a dump of all environment variables at the time of execution. This info can be useful for determining who/what is generating these actions.

    Example: $send_admin_email = "yes";

   

• Customization

  The following script variables can be altered to customize DirWrap Photo to fit your needs:

  • $new1 - This parameter determines which files will be flagged as the newest files in the script output. Files with a last modified date less than the indicated value will be tagged with the new1.gif graphic. This value represents the number of days.

    Example: $new1 = "10";

  • $new2 - This parameter determines which files will be flagged as the new files in the script output. Files with a last modified date less than the indicated value but more than the value of $new1 will be tagged with the new2.gif graphic. This value represents the number of days.

    Example: $new2 = "30";

  • $hide_ext - If set to "yes" file extensions will not be shown.

    Example: $hide_ext = "no";

  • $hide_icons - If set to "yes" file icons and thumbnails will not be shown.

    Example: $hide_icons = "no";

  • $size_as_K - If set to "yes" the size of the file will be shown in Kbytes instead of bytes.

    Example: $size_as_K = "yes";

  • $bgcolor_1 - Sets the first row's background color. Row colors will alternate between this color and the color set in $bgcolor_2. If you do not wish to have alternating row colors, set both $bgcolor_1 and $bgcolor_2 to the same value.

    Example: $bgcolor_1 = "#99dd99";

  • $bgcolor_2 - Sets the second row's background color. Row colors will alternate between this color and the color set in $bgcolor_1. If you do not wish to have alternating row colors, set both $bgcolor_1 and $bgcolor_2 to the same value.

    Example: $bgcolor_2 = "#ffffaa";

  • $wrap_photo - If set to "yes" jpeg images (as assigned in the icon associations) will be wrapped in an html template. The template used for wrapping these images must be named "photo.html" and must reside in the directory defined by $templates above. $allow_dirwrap_links set to "yes" to use this function.

    Example: $wrap_photo = "yes";

   

• Table Row/Entry Formatting

  Individual file entries are formatted as specified in the config.txt file. There two modes of output that can be used in DirWrap Photo, normal and album. In normal mode each file or directory is listed as a separate table row as defined in Normal Mode Table Formatting. In album mode each file or directory is listed as a separate table data entry with the number of entries on each table row defined by $files_per_row. The layout of each file or directory is defined as described in Album Mode Table Formatting.

  Both normal mode and album mode formatting use the same variables to define the specific data contained in an entry. These variables are:

  • $line_count = The line count in the table. Increments by one for each directory and file listed. Not valid for album mode.

  • $new_graphic = The new graphic.

  • $delete_graphic = A delete graphic linked to the file/directory delete function. Include only if you are allowing uploads and file/directory deletion.
  • $delete_link = Same as $delete graphic, without the graphic.

  • $icon_thumbnail_link = The file icon or thumbnail image. This graphic will be linked to the file.

  • $file_name_link = The file name. The file name will be linked to the file.

  • $file_size = The size of the file.

  • $modified_date = The date the file was last modified.

  • $download_counter = The file download count. Include only if you are using the download counter.
   

• Normal Mode Table Formatting

  Formatting for individual file listings is defined in the config.txt file in the section labeled:

  ######################################################################
  #                NORMAL MODE TABLE ROW FORMATTING                    #
  ######################################################################
  

  You can modify this section to fit your desired output order or to remove data you do not wish to see. If you modify this data make sure that you modify your template to match.

  IMPORTANT!!

  You must only modify the information contained between the lines reading:
  $table_row_format = <<EndRowFormat;
  and
  EndRowFormat

  You can change anything between these two lines keeping in mind the following:

  • Variable data must match the information described in Table Row/Entry Formatting above.

  • the <tr> and </tr> tags must be present. They can be modified however to match your style sheet or formatting requirements.

  • You should have at least one set of <td> </td> tags present. You can combined variables into one <td> </td> if you wish but remember to match your template to your changes.

  If no modifications are made to the normal mode table layout in config.txt, the table will contain a total of 8 columns containing the following data:

  Column 1	Column 2	Column 3	Column 4	Column 5	Column 6	Column 7	Column 7
  File # in listing	New graphics if applicable	Delete Graphic Delete Link	Folder/icon graphic/thumbnail image	File Name	File Size	Last Modified Date (MM/DD/YYYY)	Download Counts

   

• Album Mode Table Formatting

  Formatting for individual file listings is defined in the config.txt file in the section labeled:

  ######################################################################
  #                    ALBUM MODE TABLE FORMATTING                     #
  ######################################################################
  

  You can modify this section to fit your desired output order or to remove data you do not wish to see. If you modify this data make sure that you modify your template to match.

  IMPORTANT!!

  You must only modify the information contained between the lines reading:
  $table_row_format = <<EndRowFormat;
  and
  EndRowFormat

  You can change anything between these two lines keeping in mind the following:

  • Variable data must match the information described in Table Row/Entry Formatting above.

  • the <td> and </td> tags must be present. They can be modified however to match your style sheet or formatting requirements.

  If no modifications are made to the album mode table layout in config.txt, each file listing will contain the following data:

  New graphics if applicable
  Folder/icon graphic/thumbnail image
  File Name
  File Size
  Download Counts
  Delete Link

   

• Download Counter Parms

  • $use_counter - Determines whether or not DirWrap Photo's built in download counter will be used. Set to "yes" if you wish to use the download counter.

    For more info on DirWrap Photo's built in download counter refer to the Download Counter section of this document.

    Example: $use_counter = "yes";

  • $counts_file - Determines the absolute path to the file where download counts will be stored. File must exist on the server and must have write permissions. Filename can be anything you wish and is defined by this parameter. Default value and example counts file provided in the DirWrap Photo distribution is "counts.dat". This parameter is only used if $use_counter is set to "yes"

    For more info on DirWrap Photo's built in download counter refer to the Download Counter section of this document.

    Example: $counts_file = "/your/path/to/counts/file/count.dat";

  • $total_counts - Determines whether or not to total the counts for the directory. If set to "yes" a final line will be added to the listing showing total downloads in the directory. $use_counter must be set to "yes" for this option to work.

    For more info on DirWrap Photo's built in download counter refer to the Download Counter section of this document.

    Example: $total_counts = "yes";

   

• File Upload Utility Parms

  • $enable_uploads - Enables or disables the built-in file upload utility.

    Example: $enable_uploads = "yes";

  • $upload_requires_pw - Determines whether or not a password, equal to $upload_code has to be entered to use file upload utility functions (upload, make directory, delete file or directory).

    Example: $upload_requires_pw = "yes";

  • $upload_code - The password that allows access to the file upload functions of the script. Can be an alpha numeric value of any length and is case sensitive. BE SURE TO CHANGE THIS VALUE FROM THE DEFAULT!

    Example: $upload_code = "admin";

   

• Thumbnail Parms

  • $thumbnails - Enables or disables automatic thumbnail image creation and display for JPEG file.

    Example: $thumbnails = "yes";

  • $maxdimension - Sets the maximum dimension in pixels of the longest side of the thumbnail image.

    Example: $maxdimension = "100";

   

• Album Mode Parms

  • $album_mode - Determines whether or not to use album mode. If set to yes, DirWrap Photo output will be modified so that multiple files will be displayed on each table row.

    Example: $album_mode= "yes";

  • $files_per_row - Sets the number of files to display on each row in album mode.

    Example: $files_per_row = "5";

   

• Icon Associations

  Icon/File associations are defined by the %icons hash. Icons are tied to a file extension through a "key", "value" pair in the hash. You may modify these associations as you see fit keeping in mind that you must maintain the following syntax:

  "extension","icon",

  Files not included in the %icons hash are assigned a default "unknown" icon.

  Here are DirWrap Photo's default associations:

  File Type	Extensions	Icon
  Plain text	txt	text.gif
  Word	doc	word.gif
  Excel	xls	excel.gif
  PowerPoint	ppt	ppt.gif
  Rich Text Format	rtf	rtf.gif
  Adobe PDF	pdf	pdf.gif
  Font	fon	afont.gif
  True Type Font	ttf	ttfont.gif
  Sound	wav, au	sound.gif
  Music	mp3, mid	music.gif
  Compressed	zip, tar, z, gz	zip.gif
  Web	htm, html, shtml, shtm, xml	web.gif
  Video	mpg, mpeg, avi, mov, ram, rv	video.gif
  Image	gif, png, bmp, tif, tiff	pic.gif
  Scripts	js, jse, vbs, vbe, pl, pm, cgi	scripts.gif
  DLL	dll	dll.gif
  Unassigned	All other extensions	unknown.gif
  JPEG image	jpg, jpeg	Thumbnail of image if enabled, otherwise: pic.gif

   

• Error Messages

  The following error messages are defined for DirWrap Photo. These can be modified to suit your needs:

  Error Code	Variable	Indicates
  E1	$e1	An attempt was made to input a path parm with $allow_path_parm set to no
  E2	$e2	An attempt was made to use a / or .. in the start of a $path or $directory variable
  E3	$e3	An attempt was made to view to a path or directory that is hidden using @hidedirs, @hidefiles, @hideext, or $show_hidden_files set to no.
  E4	$e4	The specified directory could not be found.
  E5	$e5	An attempt was made to use a / or .. in the start of template variable
  E6	$e6	An attempt was made to view a thumbnail directory directly.
  E7	$e7	An attempt was made to perform the count subroutine on a directory.
  E8	$e8	An attempt was made to perform the count subroutine on a file that doesn't exist.

Security

In design of this script we have tried to mindful of security issues for you and your server. The script screens input so that dangerous characters are removed, and paths are verified to prevent directories below those in your $base_path from being displayed. The script also provides several different methods for hiding files and directories that you may not want displayed. Refer to the Security Parms section for details.

It is ultimately the responsibility of the user to configure and use the script in a safe manner. We highly recommend that you thoroughly read and understand the Configuration Section of this document. If you have any questions please feel free to contact us at dmag_designs@dmag.org.

To aid in making the scripts you run on your server more secure we offer the following suggestions that apply to any CGI script you chose to utilize:

• Change the name of the script. This will help protect you from known script exploits. An example of this is a vulnerability in some older versions of a popular form mail script. If you search your web logs I'll just about guarantee that you will see attempts to utilize this exploit on your server even if you don't have it installed.

• If possible hide any calls to your scripts within an SSI. DirWrap Photo provides the ability to do this. The trade off is that it usually means more work for you and you lose the ability to perform certain functions.

• Get your scripts from trusted sources.

• Run your scripts in taint mode. For PERL scripts this is controlled by including a "-T" in the first line of your script like this: #!/usr/local/bin/perl -T

  Taint mode for PERL checks the script to see if an tainted data (data that came from anywhere outside the script itself such as form input) is being used in an unsafe way. For a script to work while in taint mode this tainted data must be untainted before it can be used. A script that will run properly in taint mode indicates that the script writer has taken the time to make his scripts secure. However, there are no guarantees that this is always the case. It is possible to untaint data without really changing anything. For more information on PERL's taint mode refer to the PERL Taint Mode FAQ. Tainted data causes "Insecure Dependency" errors.

  NOTE:Older versions of the File::Find module have a bug which causes "Insecure dependency" errors when run in taint mode. DirWrap Photo uses this module to generate the recursive directory listings for the select lists on the Admin and All Counts displays. If you experience "Insecure Dependency" errors you will need to turn of taint mode to use these functions, or upgrade to the most recent version of File::Find.

• If a script contains passwords or access codes, change them from the defaults!

• Run scripts as yourself. Most webservers are set up to run scripts as a user called "nobody". To get the script to run you have to set it's permission so that this user can access it. Unfortunately, this almost always means that any other user can access it as well. Check to see if your server has a wrapper script or a method to run the script as yourself. Doing so allows you to limit the permissions of the script so that only you have permissions to run it.

• Don't trust "hidden" form input. It is a very simple matter to view the source of the document to see these values and utilize the information. Hidden files should be used to hide data to prevent cluttering your page. It should never be utilized as a security measure.

Templates

DirWrap Photo uses html templates to wrap the returned script output. There are three different template types used for DirWrap Photo:

• File/Directory Listing Templates
• Photo Wrapping Template
• Admin Template
• All Counts Template

Templates can utilize any valid html source but must meet the following requirements:

• Templates must have the file extension ".html".

• If the script is being used as a direct URL call (not SSI) the template should include the appropriate html header tags.

• File/Directory Listing Templates

  Unlike the other template types, file/directory you can utilized as many file/directory listing templates as you like. This is accomplished by supplying a template name in the DirWrap Photo call as defined in the Syntax section of this document. Templates must meet the requirements specified above and additionally the script output should be contained within a set of <table> </table> tags.

  Placing Script Output Into A File/Directory Listing Template

  Output from the script is parsed into the template by placing predefined variables into the template file. These predefined variables are:

  • %%%list%%% - The file list. This variable should be placed between <table> and </table> tags in the template.

  • %%%path%%% - The directory path as it was entered in the DirWrap Photo query string.

  • %%%directory%%% - The directory being listed from the DirWrap Photo query string.

  • %%%template%%% - The template being used. If a template was provided in the DirWrap Photo query string, this value will be passed. Otherwise, the $default_template value will be passed.

  • %%%sort%%% - The sort option. If a sort option was provided in the DirWrap Photo query string, this value will be passed. Otherwise, the $default_sort value will be passed.

  • %%%script_url%%% - Passes the value of $dirwrap_url to the template.

   

• Photo Wrapping Template

  If $wrap_photos is set to "yes", jpeg files will be wrapped in an html template.

  This template can contain any valid html markup but must meet the following requirements:

  • This template must be named "photo.html".

  • This template must the following html tag in it to display the photo:

    <imp arc="%%%imp%%%">

  Placing Script Output Into A Photo Wrapping Template

  Output from the script is parsed into the template by placing predefined variables into the template file. These predefined variables are:

  • %%%file%%% - The name of the file being displayed.

  • %%%download_count%%% - The download count for the file.

  • %%%path%%% - The directory path as it was entered in the DirWrap Photo query string.

  • %%%back_url%%% - A link back to the directory that the file was displayed from. Should be placed in a valid <a ref=""> tag as follows:

    <a ref="%%%back_url%%%">Some text or image</a>

  • %%%delete_url%%% - A link to delete the file. For use with file upload utility. Should be placed in a valid <a ref=""> tag as follows:

    <a ref="%%%delete_url%%%">Delete this file</a>

   

• Admin Template

  The admin template provides the admin html interface to the counts database file. It formats the input for the entries in the counts file.

  This template can contain any valid html markup but must meet the following requirement:

  • This template must be named "admin.html".

  Modification of this particular template is not recommended and should not be required other than supplying your own style information.

   

• All Counts Template

  The All Counts template provides a non-admin html interface to the counts database file. It formats the input for the entries in the counts file.

  This template can contain any valid html markup but must meet the following requirement:

  • This template must be named "all_counts.html".

  Modification of this particular template is not recommended and should not be required other than supplying your own style information.

• Examples

  Several template examples are included in the script download archive and on the Dirwrap Photo Main Page.

Syntax

In its most complicated form DirWrap Photo is called via URL in the following format:

http://www.your.domain/your/path/to/script/dirwrap_photo.cgi?rt=script_action&path=directory_path&template=template_name&sort=sort_option

where:

• script_action = subroutine to call in the script. If not specified the script defaults to a directory listing.

  script_action must be one of the following:

  • rt=admin - Calls the counter admin functions. No other parameters (path, template, sort) need to be specified.
  • rt=all_counts - Calls subroutine to display all entries in the counts database.

  The following script_action values are used in the course of file display and uploading and will be generated by the script or in the template (ie you should never have to actually use them in any manually written URLs) Refer to the Download Counter and File Upload Utility sections of this document for more details:

  • rt=count - Count subroutine if download counter is enabled and wrap photos is disabled.
  • rt=wrap - Subroutine to wrap jpeg files in a template. Also increments the counter if the counter is enabled.
  • rt=reset_count - Resets counts in counts database. You have to be logged in as the admin to perform this function.
  • rt=delete_count - Deletes entries in counts database. You have to be logged in as the admin to perform this function.
  • rt=cleanup_count - Cleans up counts in entries in the counts database. This removes entries for files that do not exists. You have to be logged in as the admin to perform this function.
  • rt=upload - Subroutine to upload files. Must be called from a form.
  • rt=make_dir - Subroutine to create directories.
  • rt=delete_file - Subroutine to delete files and directories.

• directory_path = the path to the directory you wish to list including the name of the directory itself. The path name cannot start with a "/" or "\".

  directory_path is optional but must be supplied if you are not using SSI!

• template_name = the name of the template without the .html extension.

  template_name is optional. If not provided the value of $default_template will be used.

• sort_option = one of the following sort options:
  • by_name: Files are sorted by file name in ascending order
  • by_r_name: Files are sorted by file name in descending order
  • by_size: Files are sorted by size in ascending order
  • by_r_size: Files are sorted by size in descending order
  • by_date: Files are sorted by last modified date in ascending order
  • by_r_date: Files are sorted by last modified date in descending order
  • by_count: Files are sorted by download count in ascending order
  • by_r_count: Files are sorted by download count in descending order

  sort_option is optional. If not supplied, the value of $default_sort will be used.

Since all of the parameters are optional (depending on how you've configured the script) the simplest DirWrap Photo URL would be:

http://www.your.domain/your/path/to/script/dirwrap_photo.cgi

Download Counter

The download counter works by creating entries in a flat file database that is incremented each time the link to a file is clicked if the feature is enabled. The download counter works by creating a call to DirWrap Photo in place of the normal file URL. This call first increments the counter, then redirects the user to the requested file.

To use the counter, set $use_counter to "yes" and set $counts_file to point to the absolute path for the counts storage file. Additionally, you can display the total counts for a directory by setting $total_counts to "yes". This will result in an additional line show total downloads for the directory.

Keep the following in mind when using the counter:

• The file defined in $counts_file must exist on the server prior to calling DirWrap Photo or you will get an error. DirWrap Photo will not create this file! The file need not contain any data, but it must be present in the path defined by $counts_file.

• It is not necessary to add any entries to the counts database file. If a file is clicked that does not already exist in the counts database file, an entry will be added automatically.

• If you are using the download counter you will not be able to hide DirWrap Photo calls even if you have $allow_dirwrap_links set to "no". This is because a call to DirWrap Photo has to be substituted for the normal file URL in order to increment the counter.

Administration Interface

DirWrap Photo includes an administration interface that allows you to reset and delete counts for individual files or for all files in the database. It also provides a cleanup utility that automatically deletes entries for files that no longer exist on the server from the database.

To access the administration interface call the script with the "rt=admin" parameter as follows:

http://www.your.domain/your/path/to/script/dirwrap_photo.cgi?rt=admin

You will be prompted to enter your "Admin Authorization Code". This code is the value you set for the script variable $admin_code. Entering this value will log you on and allow you to access the administration interface.

NOTE: This login routine will set a per-session cookie. Therefore, it is a requirement that you allow per-session cookies to utilize the administration interface.

Administration Options

You can now perform the following functions:

• Functions that work on the entire database:
  • Reset All Counts - Set the hit count for all files in the database to 0 (zero). Entries remain in the database and the first hit marker will be set to the next hit on the page.

  • Delete All Counts - Removes all entries from the database.

  • Cleanup Counts - This option checks to see if the file that each database entry refers to exists. If it does, no action is taken. if it does not, the entry is removed from the database.

• Functions that work on an individual file basis. These options are found in the "Admin" column for each file.
  • Reset - Resets the hit count for the file. The file's entry remains in the database and the first hit marker will be set to the next hit on the page.

  • Delete - Deletes the files entry in the database.

File Upload Utility

DirWrap Photo's built in file upload utility is a simple tool that allows you or other users to upload files to directories on your server through a web based interface. This feature can be enabled/disabled in your config.txt file and can also be set up so that its use requires entry of a password. Keep in mind that allowing file uploads can be a dangerous thing to do and should be approached with caution.

The upload utility supports the following functions:

• File uploads
• Directory creation
• File/directory deletion

File Uploads

<form enctype="multipart/form-data" method="post" action="%%%script_url%%%">
<input type="hidden" name="rt" value="upload">
<input type="hidden" name="upload_dir" value="%%%path%%%">
<input type="hidden" name="path" value="%%%path%%%">
<input type="file" size="30" name="upfile">
<input type="submit" value="Upload File">
</form>

where:

• %%%script_url%%% = the value defined for $dirwrap_url in config.txt

• %%%path%%% = the directory you want the file uploaded to. This value is and absolute path relative to $base_path in config.txt

If you include this form in your file listing template the %%%script_url%%% and %%%path%%% values will automatically be filled in by the script. If you chose to use a separate web page you will have to supply values to replace these two variables.

The following notes and restrictions apply to file uploading using the built-in utility:

• DirWrap Photo only supports one file upload at a time.

• File uploads cannot be performed from a query string. They must be performed from a form.

• There is currently no size limit for files being uploaded.

• File names will automatically have certain problematic and sometimes dangerous characters stripped or replaced as follows:
  • spaces are replaced with "_".
  • "&" is replaced with "and"
  • "@" is replace with "at"
  • "( ) { } [ ] < > ' ` * ! $ ~ # , ; : ^ % |" are stripped

Directory Creation

Directory Creation can be performed via html form in the following format:

<form method="post" action="%%%script_url%%%">
<input type="hidden" name="rt" value="make_dir">
<input type="hidden" name="upload_dir" value="%%%path%%%">
<input type="hidden" name="path" value="%%%path%%%">
<input name="dir_name" size="30">
<input class="button" type="submit" value="Make Directory">
</form>

where:

• %%%script_url%%% = the value defined for $dirwrap_url in config.txt

• %%%path%%% = the directory you want the new directory created. This value is and absolute path relative to $base_path in config.txt

If you include this form in your file listing template the %%%script_url%%% and %%%path%%% values will automatically be filled in by the script. If you chose to use a separate web page you will have to supply values to replace these two variables.

Directory names will be tested for unsafe characters and a file message will be returned if they are encountered.

File/Directory Deletion

Files and Directories can be deleted using a call to DirWrap Photo with the appropriate values supplied. This delete call can be automatically generated by DirWrap Photo and can be included in your file listing by supplying either the $delete_graphic or $delete_link variables in your file listing output as described in the Table Row/Entry Formatting section above.

If deleting a directory, you must delete all subdirectories first. The one exclusion is the "thumbnails" directory. The "thumbnail" directory and any file contained within it are automatically deleted when you delete the parent directory.

Using DirWrap Photo with SSI

Utilizing SSI to call DirWrap Photo through an index.shtml (or other parsable index file) is particularly useful in that it allows a user to prevent certain files in the directory from being listed and gives the user the ability to control the look of the output list.

Normally, when a URL such as http://www.your.domain/somedirectory/ is entered, and there is no index file in the directory, the web server will output a list of files on the system. While hidden files such as .htaccess are not shown, other files that you may not want people to see are. Additionally, these files are output in a list format over which you have no control unless of course you are running the server. By placing a parsable index file with an SSI call to DirWrap Photo, you can control which files are output and the look and feel of the resulting display.

In cases where the web server is set up to disallow direct listing of directories via URL (i.e. you are required to have an index file in the directory), DirWrap Photo provides a way for you to allow users to get a listing of the files in a given directory through a URL such as http://www.your.domain/somedirectory/ without having to manually create an index file that you must update every time you add or delete files for the directory. Because the DirWrap Photo output is dynamic, all you need to do is create an index file that contains an SSI call to DirWrap Photo. The index file does not need to be updated when files are added or deleted in the directory.

The safest way to call DirWrap Photo with an SSI is to use the "virtual" form of SSI.

Example:

<!--#include virtual="/cgi-bin/dirwrap/dirwrap_photo.cgi?template=template_name&path=directory_path&sort=sort_option"-->

Note that in most server configurations you should not include the "http://your.site.com/" portion of the URL to the script. While there are always exceptions, in most cases the URL will be relative to your document root.

Restrictions

• DirWrap Photo requires the PERL GD module to generate the thumbnail images.

• DirWrap Photo currently can only convert JPEG images. GIF and PNG images are not supported for thumbnail generation. Functionality may be added in a future release for PNG images but it is highly unlikely that support for GIF images will ever be implemented due to copyright issues.

• File and directory names called by DirWrap Photo cannot contain an "&". An "&" character anywhere in the path will break the DirWrap Photo call.

• If a file name is listed in the @hidefiles array any file with that name will not be displayed in any listing.
  

• If a directory name is listed in the @hidedirs array any directory with that name will not be displayed in any listing.
  

• If a file extension is listed in the @hideexts array any file with that extension will not be displayed in any listing.
  

• For security reasons and to prevent bypassing of the @hidefiles and @hidedirs values, paths and template values that begin with "/" or "\" or ".." or "." cannot be displayed. This means that the directory of your root URL (http://www.your.domain/) cannot be displayed using DirWrap Photo. This is probably desirable in most applications anyway. If you wish to display a directory in your root, create a new sub directory and then create a symbolic link to the directory you wish to list in this new directory.

• File and directory names that appear in the @hidefiles and @hidedirs arrays must be complete. Filtering is done against the full name.

• Template files must use the extension ".html". However, when calling a template the ".html" extension is not used.

• Thumbnails can only be created for files formatted as JPEG images and saved with the extension noted in the JPEG files section of the %icons hash. You can add additional extensions to the %icons hash but the thumbnails will not be generated unless the file is saved as jpeg format.

Troubleshooting

Can't get the script to run? Continually getting an error message? Here's some troubleshooting tips:

Contact us:
dmag_designs@dmag.org