/ 
CGI-ProgressBar-0.01
River stage zero No dependents
/ CGI::ProgressBar

NAME

CGI::ProgressBar - CGI.pm sub-class with a progress bar object

SYNOPSIS

use lib '..';

use CGI::ProgressBar qw/:standard/;
$| = 1;	# Do not buffer output

my $steps = 10;

print header,
	start_html('A Simple Example'),
	h1('A Simple Example'),
	p('This example will fill the screen with nonsense between updates to a progress bar.'),
	progress_bar( -from=>1, -to=>$steps );

for (1..$steps){
	print update_progress_bar;
	# Simulate being busy:
	print rand>0.5 ? chr 47 : chr 92 for 0 .. 100000;
}
print hide_progress_bar;
print p('All done.');
print end_html;
exit;

DESCRIPTION

This module provides a progress bar for web browsers.

It aims to require that the recipient client have a minimum of JavaScript 1.0, HTML 4.0, ancd CSS/1, but this has yet to be tested.

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

DEPENDENCIES

CGI

EXPORT

progress_bar
update_progress_bar
hide_progress_bar

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//;".

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.

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 (CGI) object - specifically in the field progress_bar, which we create as an array.

from
to

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

width
height

The width and height of the progress bar, in pixels. Cannot accept percentages (yet). Defaults: 400, 20.

blocks

The number of blocks to appear in the progress bar. Default: 100.

gap

The amount of space between blocks, in pixels. Default: 1.

label

Supply this parameter with a true value to have a numerical display of progress.

FUNCTION/METHOD update_progress_bar

Updates the progress bar.

FUNCTION/METHOD hide_progress_bar

Hides the progress bar.

CSS STYLE CLASS EMPLOYED

pblib_bar

A DIV containing the whole progress bar, including any accessories (such as the label). The only attribute used by this module is width, which is set dynamically. The rest is up to you. A good start is:

padding:    2 px;
border:     solid black 1px;
text-align: center;
pblib_block

An individual block within the status bar. The following attributes are set dynamically: width, height, margin-right.

pblib_number

Formatting for the label text (part of which is actually an input type='text' element. border and text-align are used here, and the whole appears centred within a table.

BUGS, CAVEATS, TODO

One bar per page

This may change.

Parameter passing doesn't match CGI.pm

But it will in the next release if you ask me for it.

colors not implimented

I'd like to see here something like the Tk::ProgressBar::colors; not because I've ever used it, but because it might be cool.

Horizontal orientation only

You can get around this by adjusting the CSS, but you'd rather not. And even if you did, the use of -label might not look very nice. So the next version will support an -orientation option.

Inline CSS and JS

Because it's easiest for me. I suppose some kind of over-loading of the CGI::start_html would be possible, but then I'd have to check it, and maybe update it, every time CGI.pm was updated, which I don't fancy.

AUTHOR

Lee Goddard <lgoddard -at- cpan -dot- org>

Copyright (C) Lee Goddard, 2002-2003. All Rights Reserved. This software is made available under the same terms as Perl itself. You may use and redistribute this software under the same terms as Perl itself.

KEYWORDS

HTML, CGI, progress bar, widget

SEE ALSO

perl. CGI, Tk::ProgressBar,

4 POD Errors

The following errors were encountered while parsing the POD:

Around line 182:

You forgot a '=back' before '=head2'

Around line 210:

'=item' outside of any '=over'

Around line 305:

You forgot a '=back' before '=head1'

Around line 340:

You forgot a '=back' before '=head1'