view release on metacpan or  search on metacpan

lib/Apache/AxKit/Plugin/Upload.pm  view on Meta::CPAN

1;
__END__

=head1 NAME

Apache::AxKit::Plugin::Upload - upload tracking for AxKit

=head1 SYNOPSIS

In .htaccess:

  AxAddPlugin Apache::AxKit::Plugin::Upload
  PerlSetVar AxUploadStatusDir data/upload
  PerlSetVar AxUploadStatusLocation /data/upload
  PerlSetVar DisableUploads Off
  PerlSetVar MaxPostSize 30485760
  LimitRequestBody 30485760

Put this code on the form: (example using XSP)

  <form enctype="multipart/form-data" action="process.xsp?axkit_upload_id={$r->connection->user|"
      onsubmit="window.open('http://'+location.hostname+'{$r->dir_config('AxUploadStatusLocation').'/'.$r->connection->user}.html','axkit_upload','height=80,width=320,height=80')">
      ...
  </form>

=head1 DESCRIPTION

This plugin allows you to show a progress bar while uploading big files. This works
by opening a small window via JavaScript. That window is directed to a self-refreshing
HTML page which is continuously updated by this plugin.

Usually, three URLs are involved: The page starting the upload, the page receiving the
upload, and the status page. The receiving page I<must> have "axkit_upload_id=..." in
the I<query string>. That ID is used to identify the specific upload. Use a username or
a session ID or even a random number. You cannot have more than one upload for one ID.
The status page is named <AxUploadStatusDir>/<ID>.html

Set AxUploadStatusDir to where the files should be stored. Relative paths get
$r->document_root prepended. Set AxUploadStatusLocation to where the client can get
the files in AxUploadStatusDir.

=head2 Advanced Configuration

If you want to process the received data and the processing is slow, you can extend the
progress bar to include your custom status. To do so, set

  PerlSetVar AxUploadCustom On

and call:

  Apache::AxKit::Plugin::Upload::progress($done,$total,"Processing... ($done/$total)");

regularly to update the progress bar. The window will automatically close when
$done == $total.

To see if an upload is already running, call:

  Apache::AxKit::Plugin::Upload::is_running($r,$id)

In some constellations, the upload progress bar won't appear or shows a 404. This
highly depends on your file layout. To fix that problem, create a tiny script that does:

  Apache::AxKit::Plugin::Upload::init($r,$id)
      if (!Apache::AxKit::Plugin::Upload::is_running($r,$id));

and then redirects to <AxUploadStatusLocation>/<ID>.html. Call this script instead of
<AxUploadStatusLocation>/<ID>.html.

=head1 AUTHOR and LICENSE

Copyright (C) 2004, Jörg Walter.

This plugin is licensed under either the GNU GPL Version 2, or the Perl Artistic
License.

=cut