view release on metacpan or  search on metacpan

javascript.pod  view on Meta::CPAN

=head1 NAME

JavaScript_Guide for Apache::UploadMeter

=head1 SYNOPSIS

    // Register a global callback
    UploadMeter.Responders.register({
        onCreate: function (meter) {
            Element.update(meter.desc, "Please wait...");
        }
    });
    
    // Create a new UploadMeter
    var um = new UploadMeter(el, meter_id, meter_url, {
        // Callback to be executed every time we get a status update
        onUpdate: function (status, last) {
            Element.update('file', "Now uploading: " + status.filename);
            Element.update('bytes', status.seen + "/" + status.total + "  bytes transfered (" + Util.formatDec(status.currentrate) + " bytes/sec)");
            Element.update('time', Util.formatTime(status.elapsed) + " elapsed (" + Util.formatTime(status.remaining) + " remaining)"); 
        },
        onFinished: function(status, last) {
        // Callback to be executed when we've detected a complete upload and stop the meter
            Element.show('closeme');
        }
    });
    
    // Start our uploadmeter - only do this once the corresponding upload has started (or is about to start)
    um.start();
    
    // Stop (or pause) a previouslky start()ed meter
    um.stop();
    
    // Un-register the default pop-up window behavior 
    Event.stopObserving(aum_el, 'submit', aum_popup);

=head1 DESCRIPTION

Apache::UploadMeter includes several JavaScript objects to help quickly create
a customized GUI interface for Apache::UploadMeter using the JSON meter type

=head1 DOM, JavaScript and Cascading StyleSheet rules

Although we aim to give maximum customizability, in order to keep a balance between
ease of initial set-up and basic usage, and customizability, the built-in UploadMeter
includes JS code and CSS rules for a simple graphical progress-bar.  At the
current moment, the constructor for the UploadMeter object requires a reference
to a DOM node as one of the parameters, to be used as the base for creating this
progress bar.  If you don't want to use the built-in progress-bar, but also don't
want to muck with the UploadMeter object to get around this, just create an empty
DIV on your page, set the style to hidden (eg, display: none), and pass that to
the UploadMeter object.  If you do wish to use this built-in object, ensure that
the CSS class of this div is "uploadmeter" (and don't hide it!)

Also, it is worth noting that the default behavior looks for an element class
named "uploadform" and attempts to add to the onSubmit code for it, to trigger
the bundled default pop-up window.  If you don't want this to happen, just run:

C<Event.stopObserving(aum_el, 'submit', aum_popup);>


=head1 API Documentation

=head3 UploadMeter Object

This is where most of the action happens.  The public interface to this object
consists of a constructor, start and stop methods, and some callbacks that can 
be used to do extra stuff at various key points in the UploadMeter's lifetime.

=over

=item *
UploadMeter(I<Element>, I<Meter-Id>, I<Meter-URL>, I<options>)

This is the default constructor for a new UploadMeter instance.  It accepts 3
mandatory parameters and a hash of additional options.  The first parameter,
I<Element> is a DIV element under which to create a graphical progress-bar (see
L<DOM, JavaScript and Cascading StyleSheet rules> above).  The second parameter
is the unique identifier of the uploadmeter data you wish to use.  If you're using
MeterType JSON, this will be embedded in your JavaScript as I<meter_id>.  The
third parameter is the URL of the meter-status URL.  If you're using
MeterType JSON, this will be embedded in your JavaScript as I<meter_url>.

The final parameter is a hash of additional optional configuration directives and
callback routines.

=over

=item *
Parameters

=over

=item *
delay

The delay (in seconds or partial seconds) between meter updates.  The default
value (3) should probably be good enough for you.  As a warning, if you set this
too high, your users will not have a good feel for what's happening.  Too low and
(besided the extra traffic to your server), the animation for the progress-bar
may garble (this is known to happen if 2 animation requests happen simultaniously.
While this will likely eventually be fixed, as of the time of writing, it's not.

=back

=item *
Callback routines

The callback routines all contain zero, one or two parameters.  The parameter
order will always be I<status>, I<last>.

I<status> contains the current status of the upload.  I<last> always contains
the B<previous> status of the uploadmeter, such that on a repeating callback
such as onUpdate, the value of any given request's I<last> will always be the
same as the previous callback's I<status>.