view release on metacpan or  search on metacpan

lib/Apache/UploadMeter.pm  view on Meta::CPAN

        }
        $tmp->{$_} = $dir->{$_};
    } qw(UploadMeter UploadHandler UploadForm);
    $tmp->{MeterType} = $dir->{MeterType} || "JSON";
    map {
        $tmp->{MeterOptions}{uc($_)}=1;
        } split(/\s/,$dir->{'MeterOptions'}) if defined($dir->{'MeterOptions'});
    $tmp->{MeterName} = $val;
    
    $self->{'meters'}{$val} = $tmp;
    my ($UH, $UF, $UM, $TYPE) = ($tmp->{UploadHandler},
                                 $tmp->{UploadForm},
                                 $tmp->{UploadMeter},
                                 $tmp->{MeterType},
                                 );
    my $config = <<"EOC";
<Location $UH>
    Options +ExecCGI
    PerlInitHandler Apache::UploadMeter::upload_jit_handler
</Location>
<Location $UF>
    Options +ExecCGI
    PerlInitHandler Apache::UploadMeter::form_jit_handler
</Location>
<Location $UM>
    Options +ExecCGI
    PerlInitHandler Apache::UploadMeter::meter_jit_handler
</Location>
PerlModule Apache::UploadMeter::Resources::XML
<Location $UM/styles/xml/aum.xsl>
    SetHandler perl-script
    PerlResponseHandler Apache::UploadMeter::Resources::XML::xsl
</Location>
<Location $UM/styles/xml/aum.xsd>
    SetHandler perl-script
    PerlResponseHandler Apache::UploadMeter::Resources::XML::xsd
</Location>
PerlModule Apache::UploadMeter::Resources::JavaScript
<Location $UM/styles/js/prototype.js>
    SetHandler perl-script
    PerlResponseHandler Apache::UploadMeter::Resources::JavaScript::prototype
</Location>
<Location $UM/styles/js/behaviour.js>
    SetHandler perl-script
    PerlResponseHandler Apache::UploadMeter::Resources::JavaScript::behaviour
</Location>
<Location $UM/styles/js/scriptaculous.js>
    SetHandler perl-script
    PerlResponseHandler Apache::UploadMeter::Resources::JavaScript::scriptaculous
</Location>
<Location $UM/styles/js/aum.js>
    SetHandler perl-script
    PerlResponseHandler Apache::UploadMeter::Resources::JavaScript::json_js
</Location>
PerlModule Apache::UploadMeter::Resources::CSS
<Location $UM/styles/css/aum.css>
    SetHandler perl-script
    PerlResponseHandler Apache::UploadMeter::Resources::CSS::json_css
</Location>
PerlModule Apache::UploadMeter::Resources::HTML
<Location $UM/styles/aum_popup.html>
    SetHandler perl-script
    PerlResponseHandler Apache::UploadMeter::Resources::HTML::json_popup
</Location>

EOC

    $parms->server->add_config([split /\n/, $config]);
    $parms->server->log->info("Configured $namespace v$VERSION \"$val\" $UH - $UM - $UF [$TYPE]");
}

sub configure_invalid {
    my ($self, $parms, $val) = @_;
    my $conf = $parms->info;
    die "Error: $conf must appear inside an <UploadMeter> container";
}

sub configure_end {
    my ($self, $parms, $val) = @_;
    my $conf = $parms->info;
    die "Error: </UploadMeter> without opening <UploadMeter>";
}

1;
__END__

=head1 NAME

Apache::UploadMeter - Apache module which implements an upload meter for form-based uploads

=head1 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"/>

lib/Apache/UploadMeter.pm  view on Meta::CPAN

=item *
UploadForm

This should point to the URI on the server which contains the upload form with
the special E<lt>!--#uploadform--E<gt> tag.  Note that there should NOT be an
opening E<lt>FORME<gt> tag, but there SHOULD be a closing E<lt>/FORME<gt>
tag on the HTML page.

=item *
UploadHandler

This should point to the target (eg, ACTION) of the upload form.  The target
should already exist and do something useful.

=item *
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.

=item *
MeterType

Optional parameter specifying the type of pre-bundled meter (see L<BUILT-IN TYPES>
below).  If this parameter is omitted, JSON is assumed as the default value.

=item *
MeterOptions

Optional set of parameters for the meter (space delimited).  Can include one or
more of the following:

=over

=item *
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

=back

=back

=back

=head1 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

=head1 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 I<JSON> or I<XML> in
the MeterType configuration directive.  Each of these will cause
Apache::UploadMeter to add relevant code to your upload form page.

=head1 CUSTOMIZATION

Additionally, I<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:

=over

=item *
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).

=item *
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 L<DATA FORMAT>, above.

=item *
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
I<meter_id> is not found on the server, a 404 error will be immediately returned.

=back

=head1 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.

=head1 AUTHOR AND COPYRIGHT

Copyright (c) 2001-2007 Issac Goldstand E<lt>margol@beamartyr.netE<gt> - All rights reserved.