download.cgi -- Organize a download directory
RULES file example syntax:
printfile MyHtmlTopStuff.html
print <h2>tar files:</h2> list .*\.tar\.(gz|bz2)
print <h2>zip files:</h2> list .*\.zip
ignore *~
Typically this can be installed by simply copying it to the directory it should serve and renaming it to index.cgi (e.g. /var/www/my-server/download/index.cgi) . Make sure to make it executable and make sure to create a RULES file for it to read.
You may need to set the ExecCGI option in an apache .htaccess file or httpd.conf file as well:
Options +ExecCGI
In addition, if your server doesn't support the .cgi extension, make sure this line is uncommented in your httpd.conf file:
AddHandler cgi-script .cgi
The script works by first reading in the RULES. file and caching the results. Each line is expected to be a comment (prefixed by a #), a blank line or a configuration token (described in the next section) followed by argument(s) to the end of the line.
The download.cgi script will then read in the directory in which it was placed and process each file according to the ordered set of rules loaded. The first matching rule will win and the output will be generated based on that rule.
There are a few different types of syntax lines can go into the RULES file. Per typical configuration files, lines starting with a # will be ignore as a comment.
Note: Configuration lines must not start with white-space, as this will be used to add optional configuration tokens to the rules in the future and the code already treats white-space starting lines differently.
Rule options can be created by prefixing a line with a white-space character. Thus, the following is a valid single rule definition that adds the "versionspaces" option to the rule:
list .*.rpm
versionspaces 1
The printefile directive takes a single argument and simply dumps that file out. It's functionally equivelent to a "include" statement.
The print token simply prints the rest of the line to the output page. It is useful especially for quick header syntax above a list.
This is the real power behind the download.cgi script. This allows you to group files in a directory by regular expression matching. The list will be printed using HTML <ul> and <li> style tags [future versions will allow for a more flexible output style].
The list will be sorted by version numbers as best as possible. The first number after a - will be considered the start of a version number and high version numbers will be sorted to higher in the displayed list (so 1.7.1 will be above 1.7). The version sorting algorithm treats .preN and .rcN suffixes differently so that 1.7.1.pre1 will be sorted below 1.7.1. [future versions will allow for a more flexible output style].
Note: make sure you realize that a regular expression is required and typical unix globbing is not supported (yet). IE, "*.tar.gz" is not a valid argument.
Extra options:
This adds a verical space between files of different versions. This is most useful for grouping file sets together such as multilpe RPMs that make up a single version set.
list mypackage.*.rpm
versionspaces 1
This adds version headers ahead of each section with different versions so the results look something like:
+ 1.3
+ dnssec-tools-1.3.rpm
+ dnssec-tools-libs-1.3.rpm
+ 1.2
+ dnssec-tools-1.2.rpm
+ dnssec-tools-libs-1.2.rpm
This binds multiple suffixes together so that all similar file types end up on the same line. For example, if you distribute both .tar.gz files as well as .zip and maybe .tar.gz.md5 and .zip.md5, then the following line:
list mypackage.*(zip|tar.gz)
suffixes .tar.gz .zip .tar.gz.md5 .zip.md5
Will offer all downloads on a single lien that will look roughly like:
+ dnssec-tools-1.2.tar.gz | [.zip] [.tar.gz.md5] [.zip.md5]
(assuming all the files were available, otherwise the missing ones are excluded)
This will add the date for the last modification time of the file. If this is desired for all lists, use the 'global' property to set this globally.
This means that a given file may be listed more than once in the results output. Normally once a file is matched, it will be marked as "done" and not shown again even if another rule matches the same file. This option, when set on a match, means it won't mark it so future rules will still be able to match it. Also, if set on a later rule even after a previous rule marked it as done, it'll ignore the 'done' mark and show it anyway.
This lets you set global parameters that affect all the rules. For example, you can have versionspaces turned on for all rules by putting this at the top of the file:
global versionspaces 1
global versionheaders 1
This lets you name sections of the output for showing/hiding using the buttonbar token.
Sub-options for this include:
If set to 1, sub-directories will be decended into and all matching files in the entire directory tree will be looked for. list and other regexps will match the whole subdirectory-to-file path (but make sure you include proprly escaped slashes, like \/, when creating regular expressions with path components in them).
Each named entry will get a <div> wrapper with a CSS classname of dcgiLevelN attached to it. This is useful for creating hierarchical sets of CSS-designable sections. Deeper levels of N will nested within higher ones. Additionally the buttonbar entries will be grouped into <span> sections as well so they can be structured using CSS.
If a buttongroup specification exists, all the various buttons for the button bar will be grouped under a separate NAME section (after the level sections). The NAME will be printed before the row of buttons and will be printed in alphabetical order.
If the NAME is prepended with numerical digits, the group will be sorted and printed within the normal level sets but the number will be stripped before displaying the name.
The special buttongroup name of 'no' will hide cause the button for that box not to be printed at all.
If the hide sub-token is specified (and is non-zero) then this section will default to being hidden.
This lets the entry be hidden by default unless the browser's usage-agent matches a particular string. This is most useful when STRING contains things like "Linux", "Windows" and "Macintosh" so that only sections are shown that match the operating system of the user.
This is a convenience token that translates the results into the equivalent of:
name TITLE
level N
[any other specified options]
print <a name="gotoTITLE" />
print <hN>TITLE</hN>
This token can be placed in the output and a bar of buttons that toggle on/off sections of the page will be created.
Because this makes use of jquery, you'll need to add a source line to the html header for pulling in the jquery code from somewher. Such as:
print <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.3/jquery.min.js"></script>
If the maxlevel token is applied to the buttonbar line, then no buttons at a deth greater than N will be printed. This is useful when you have a big hierarchy and the buttons get too messy with all of them showing up showing.
Sets the label printed to the left of the buttonbar. This defaults to "Show Files:" if not set. To erase the label, set it to .
These change the hide/show image src parameters of the button box to the URL spec. They default to 'hidebutton.svg' and 'showbutton.svg'. Examples of these can be found in the examples directory.
This allows files to be ignored so that error messages about unknown files don't get printed to the web server's error log.
This will likely only work with apache as the script expects the SCRIPT_FILENAME environment variable to be set, which may be an apache-ism.
The output is rather plain unless some CSS rules are applied. See the download-style.css file in the example directory for a starting set of CSS rules to add to the results.
See the example directory for an example rule set and files to test with. Start by looking at the RULES file. If you want to test the directory, place it in a web server, copy the download.cgi script into it (I suggest naming it index.cgi so the web server will automatically pick it up as an index) and then point your web browser at it.
The following features would be 'nice to haves:'
- sort by various other methods - URL prefix other than current - generic list formatting mechanism - hover notes - caching of data for speed (based on directory modification time)
Wes Hardaker <opensource AT hardakers DOT net>
Copyright (c) 2010-2013 Wes Hardaker
All rights reserved. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.