view release on metacpan or  search on metacpan

lib/CGI/ProgressBar.pm  view on Meta::CPAN

	$| = 1;	# Do not buffer output
	print header,
		start_html(
			-title=>'A Simple Example',
			-style=>{
				-src  => '', # You can override the bar style here
				-code => '', # or inline, here.
			}
		),
		h1('A Simple Example'),
		p('This example will update a JS/CSS progress bar.'),
		progress_bar( -from=>1, -to=>100 );
	# We're set to go.
	for (1..10){
		print update_progress_bar;
		# Simulate being busy:
		sleep 1;
	}
	# Now we're done, get rid of the bar:
	print hide_progress_bar;
	print p('All done.');
	print end_html;
	exit;

=head1 DESCRIPTION

This module provides an HTML/JS progress bar for web browsers, to keep end-users occupied when otherwise
nothing would appear to be happening.

It aims to require that the recipient client have a minimum
of JavaScript 1.0, HTML 4.0, and CSS/1.

All feedback would be most welcome. Address at the end of the POD.

=cut

use 5.004;

=head2 DEPENDENCIES

	CGI

=cut

our $VERSION = '0.05';

BEGIN {
	use CGI::Util; # qw(rearrange);
	use base 'CGI';

=head2 EXPORT

	progress_bar
	update_progress_bar
	hide_progress_bar

=cut

	no strict 'refs';
	foreach (qw/ progress_bar update_progress_bar hide_progress_bar/){
		*{caller(0).'::'.$_} = \&{__PACKAGE__.'::'.$_};
	}
	use strict 'refs';
}

=head1 USE

The module sub-classes CGI.pm, providing three additional methods (or
functions, depending on your taste), each of which are detailed below.

Simply replace your "use CGI qw//;" with "use CGI::ProgressBar qw//;".

Make sure you are aware of your output buffer size: C<$|=$smothingsmall>.

Treat each new function as any other CGI.pm HTML-producing routine with
the exception that the arguments should be supplied as in OOP form. In
other words, the following are all the same:

	my $html = $query->progress_bar;
	my $html = progress_bar;
	my $html = progress_bar(from=>1, to=>10);
	my $html = $query->progress_bar(from=>1, to=>10);
	my $html = $query->progress_bar(-to=>10);

This will probably change if someone would like it to.

=head1 FUNCTIONS/METHODS

=head2 FUNCTION/METHOD progress_bar

Returns mark-up that instantiates a progress bar.
Currently that is HTML and JS, but perhaps the JS
ought to go into the head.

The progress bar itself is an object in this class,
stored in the calling (C<CGI>) object - specifically
in the field C<progress_bar>, which we create.
(TODO: Make this field an array to allow multiple bars per page.)

=over 4

=item from

=item to

Values which the progress bar spans.
Defaults: 0, 100.

=item orientation

If set to C<vertical> displays the bar as a strip down the screen; otherwise,
places it across the screen.

=item width

=item height

The width and height of the progress bar, in pixels. Cannot accept
percentages (yet). Defaults: 400, 20, unless you specify C<orientation>
as C<vertical>, in which case this is reversed.