NAME
Apache::UploadMeter - Apache module which implements an upload meter for form-based uploads
SYNOPSIS
XML-based graphical meter (in httpd.conf)
PerlLoadModule Apache::UploadMeter
<UploadMeter MyUploadMeter>
UploadForm /form.html
UploadHandler /perl/upload
UploadMeter /perl/meter
MeterType XML
</UploadMeter>
(in /form.html)
<!--#uploadform-->
<INPUT TYPE="FILE" NAME="theFile"/>
<INPUT TYPE="SUBMIT"/>
</FORM>Web 2.0 JS-based graphical meter (in httpd.conf)
PerlLoadModule Apache::UploadMeter
<UploadMeter MyUploadMeter>
UploadForm /form.html
UploadHandler /perl/upload
UploadMeter /perl/meter
MeterType JSON
</UploadMeter>
(in /form.html)
<FORM ACTION="/perl/upload" ENCTYPE="multipart/form-data" METHOD="POST" class="uploadform">
<INPUT TYPE="FILE" NAME="theFile"/>
<INPUT TYPE="SUBMIT"/>
</FORM>
<DIV class="uploadmeter"></DIV>ONLINE DEMO
An online demo of a (fairly) up-to-date version of the progress meter can be seen at http://uploaddemo.beamartyr.net/ [To conserve bandwidth, this URL won't allow more than 5MB of uploaded data. An attempt to upload more than that will cause the upload to be prematurely canceled, so try to ensure the total size of the files to be uploaded there is less than 5MB]
DESCRIPTION
Apache::UploadMeter is a mod_perl module which implements a status-meter/progress-bar to show realtime progress of uploads done using a form with enctype=multipart/form-data.
The software includes several built-in DHTML widgets to display the progress bar out-of-the box, or alternatively you can create your own custom widgets.
To use the enclosed JavaScript powered widget, simply modify the <form> tag to include class="uploadform".
To use the XML/XSL powered widget, simply replace the existing opening <FORM> tag, with the a special directive <!--#uploadform-->.
NOTE: To use this module, mod_perl MUST be built with StackedHandlers enabled.
CONFIGURATION
Configuration is done in httpd.conf using <UploadMeter> sections which contain the URLs needed to manipulate each meter. Currently multiple meters are supported with the drawback that they must use distinct URLs (eg, you can't have 2 meters with the same UploadMeter path).
<UploadMeter MyMeter> Defines a new UploadMeter. The MyMeter parameter specifies a unique name for this uploadmeter. Currently, names are required and must be unique.
In a future version, if no name is given, a unique symbol will be generated for the meter.
Each UploadMeter section requires at least 2 sub-parameters
UploadForm
This should point to the URI on the server which contains the upload form with the special <!--#uploadform--> tag. Note that there should NOT be an opening <FORM> tag, but there SHOULD be a closing </FORM> tag on the HTML page.
UploadHandler
This should point to the target (eg, ACTION) of the upload form. The target should already exist and do something useful.
UploadMeter
This should point to an unused URI on the server. This URI will be used to provide the progress-meter data. If legacy XML/XSL mode is used, this will also provide the actual meter window.
MeterType
Optional parameter specifying the type of pre-bundled meter (see "BUILT-IN TYPES" below). If this parameter is omitted, JSON is assumed as the default value.
MeterOptions
Optional set of parameters for the meter (space delimited). Can include one or more of the following:
JSON-LITE
Don't include external JavaScript dependencies by default. If you specify this option make sure you already include compatible versions of JavaScript dependencies in your pages, or you may get errors.
Current requred libraries are:
Prototype-1.5.0 Behaviour-1.1 Scriptaculous-1.7.0
DATA FORMAT
Apache::UploadMeter currently provides 2 types of meters: JavaScript (JSON) based, and XML-based. The JSON is the new default; it's sexier, slicker, works out-of-the-box with modern browsers, and with the magic of AJAX and DHTML, doesn't even need a popup window. XML is also still actively supported and is aimed at users who wish to further customize the user-experience or provide a non-browser based UploadMeter. Both JSON and XML provide identical data; a formal XSL schema can be seen at http://uploaddemo.beamartyr.net/demo/xml/meter/styles/xml/aum.xsd
BUILT-IN TYPES
Apache::UploadMeter comes pre-bundled with 2 DHTML-based graphical meters that can be used as-is, or just as reference points for builing your own custom meters. Currently the 2 types can be selected by specifying JSON or XML in the MeterType configuration directive. Each of these will cause Apache::UploadMeter to add relevant code to your upload form page.
CUSTOMIZATION
Additionally, NONE can be specified, which will allow you to customize your user-experience without using any of the built-in meters. To use this, you must define your own widget, and query the UploadMeter URL on your own.
The UploadMeter currently accepts the following parameter:
meter_id
The meter identifier. This must be unique across all meters on the server. A future version of this library will likely require that this be server-generated and will embed this in the HTML form, either in JavaScript or elsewhere in the DOM tree, but for now, you can specify anything you like (as long as each is unique).
format
This determines the data format that the meter will return. Currently JSON can be specified to return a JSON structure, otherwise an XML structure will be returned. See "DATA FORMAT", above.
returned
This is a boolean (0 or 1) value used to help reduce race conditions when a new upload is initiated. If it is 0 or not defined, the server will cause the request to block (for up to 15 seconds by default - overridable by setting $Apache::UploadMeter::TIMEOUT) until the uploading content is detected by the server and the meter's datastructure is initialized. If it is 1, and the meter_id is not found on the server, a 404 error will be immediately returned.
COMPATIBILITY
Beginning from version 0.99_01, this module is only compatible with Apache2/mod_perl2 Support for Apache 1.3.x is discontinued, as it's too damn complicated to configure in Apache 1.3.x This may change in the future, but I doubt it; servers are slowly but surely migrating from 1.3 to 2.x Maybe it's finally time for you to upgrade too.
AUTHOR AND COPYRIGHT
Copyright (c) 2001-2007 Issac Goldstand <margol@beamartyr.net> - All rights reserved.
This library is free software. It can be redistributed and/or modified under the same terms as Perl itself.
This software contains third-party components licensed under BSD and MIT style open-source licenses.
SEE ALSO
Apache2::Request(3)