File Coverage

blib/lib/CGI/ProgressBar.pm

Criterion	Covered	Total	%
statement	77	90	85.5
branch	17	34	50.0
condition	1	3	33.3
subroutine	13	13	100.0
pod	3	3	100.0
total	111	143	77.6

line

stmt

bran

cond

sub

pod

time

code

1

1

9548

use strict;

1

2

1

48

2

1

6

use warnings;

1

3

1

57

3

4

package CGI::ProgressBar;

5

6

=head1 NAME

7

8

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

9

10

=head1 SYNOPSIS

11

12

use strict;

13

use warnings;

14

use CGI::ProgressBar qw/:standard/;

15

$| = 1; # Do not buffer output

16

print header,

17

start_html(

18

-title=>'A Simple Example',

19

-style=>{

20

-src => '', # You can override the bar style here

21

-code => '', # or inline, here.

22

}

23

),

24

h1('A Simple Example'),

25

p('This example will update a JS/CSS progress bar.'),

26

progress_bar( -from=>1, -to=>100 );

27

# We're set to go.

28

for (1..10){

29

print update_progress_bar;

30

# Simulate being busy:

31

sleep 1;

32

}

33

# Now we're done, get rid of the bar:

34

print hide_progress_bar;

35

print p('All done.');

36

print end_html;

37

exit;

38

39

=head1 DESCRIPTION

40

41

This module provides an HTML/JS progress bar for web browsers, to keep end-users occupied when otherwise

42

nothing would appear to be happening.

43

44

It aims to require that the recipient client have a minimum

45

of JavaScript 1.0, HTML 4.0, and CSS/1.

46

47

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

48

49

=cut

50

51

1

22

use 5.004;

1

9

1

67

52

53

=head2 DEPENDENCIES

54

55

CGI

56

57

=cut

58

59

our $VERSION = '0.05';

60

61

BEGIN {

62

1

794

use CGI::Util; # qw(rearrange);

1

11222

1

73

63

1

10

use base 'CGI';

1

3

1

19355

64

65

=head2 EXPORT

66

67

progress_bar

68

update_progress_bar

69

hide_progress_bar

70

71

=cut

72

73

1

17796

no strict 'refs';

1

3

1

292

74

1

3

foreach (qw/ progress_bar update_progress_bar hide_progress_bar/){

75

3

5

*{caller(0).'::'.$_} = \&{__PACKAGE__.'::'.$_};

3

1527

3

17

76

}

77

1

5

use strict 'refs';

1

2

1

25

78

}

79

80

=head1 USE

81

82

The module sub-classes CGI.pm, providing three additional methods (or

83

functions, depending on your taste), each of which are detailed below.

84

85

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

86

87

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

88

89

Treat each new function as any other CGI.pm HTML-producing routine with

90

the exception that the arguments should be supplied as in OOP form. In

91

other words, the following are all the same:

92

93

my $html = $query->progress_bar;

94

my $html = progress_bar;

95

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

96

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

97

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

98

99

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) object - specifically

in the field C, 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 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

as C, in which case this is reversed.

=item blocks

The number of blocks to appear in the progress bar.

Default: 10. You probably want to link this to C and C

or better still, leave it well alone: it may have been a mistake to even include it.

C is an alias for this attribute.

=item label

Supply this parameter with a true value to have a numerical

display of progress. Default is not to display it.

=item layer_id

Most HTML elements on the page have C attributes. These

can be accessed through the C field, which is a hash

with the follwoing keys relating to the C value:

=item mycss

Custom CSS to be written inline (ugh) after any system CSS.

=over 4

=item form

The C

=item container

The C

containing everything we display.

=item block

This value is used as a prefixed for the C of each block of the bar,

with the suffix being a number incremented from C<1>.

=item number

The digits being updated as the bar progresses, if the option is enabled.

=back

=back

=cut

our $CSS = '';

sub progress_bar {

5

10863

local $_;

5

9

my ($self,%args);

5

173

($self,@_) = &CGI::self_or_default(@_);

5

118

my $pb = bless {

_updates=> 0, debug => undef,

mycss => '', orientation => 'horizontal',

from => 1, to => 100, width => '400',

height => '20', blocks => 10,

label => 0, colors => [100,'blue'],

},__PACKAGE__;

5

20

if (ref $_[0] eq 'HASH'){ %args = %{$_[0]} }

0

0

0

0

5

14

elsif (not ref $_[0]){ %args = @_ }

else {

0

0

warn "Usage: \$class->new( keys=>values, )";

0

0

return undef;

}

5

15

foreach my $k (keys %args){

3

5

my $nk = $k;

3

7

$nk =~ s/^-(.*)$/$1/;

3

9

$pb->{$nk} = $args{$k};

}

5

16

$pb->{blocks} = $args{steps} if $args{steps};

5

15

$pb->{orientation} = 'vertical' if $pb->{orientation} eq 'v';

5

13

if ($pb->{orientation} eq 'vertical'){

0

0

my $w = $pb->{width};

0

0

$pb->{width} = $pb->{height};

0

0

$pb->{height} = $w;

}

5

11

$pb->{colors} = $pb->{colors}? {@{$pb->{colors}}} : {100=>'blue'};

5

20

5

17

$pb->{_length} = $pb->{to} - $pb->{from}; # Units in the bar

5

8

$pb->{_interval} = 1; # publicise?

# $pb->{_interval} = $pb->{_length}>0? ($pb->{_length}/$pb->{blocks}) : 0;

5

22

$pb->{block_wi} = int( $pb->{width} / $pb->{blocks} ) -2;

# IN A LATER VERSION....Store ourself in caller's progress_bar array

# push @{ $self->{progress_bar} },$pb;

5

9

$self->{progress_bar} = $pb;

5

19

for my $k (qw[ from to blocks _interval ]){

20

61

$pb->{$k} = int($pb->{$k});

}

5

15

if ($pb->{debug}){

0

0

require Data::Dumper; import Data::Dumper;

0

0

0

0

warn 'New CGI::ProgressBar '.Dumper($pb);

0

0

warn 'Total blocks='.($pb->{blocks});

0

0

warn 'Expected total calls='.($pb->{to}/$pb->{_interval});

}

5

18

return $self->_pb_init();

}

=head2 FUNCTION/METHOD update_progress_bar

Updates the progress bar.

=cut

sub update_progress_bar {

# my ($self, @crud) = CGI::self_or_default;

1

568

return "\n";

}

=head2 FUNCTION/METHOD hide_progress_bar

Hides the progress bar.

=cut

sub hide_progress_bar {

1

231

my ($self, @crud) = CGI::self_or_default;

#my $pb = $self->{progress_bar}[$#{$self->{progress_bar}}];

1

20

return $self->{progress_bar}?

"\n"

: '' ;

}

=head1 CSS STYLE CLASS EMPLOYED

You can add CSS to be output into the page body (ugh) in the C field.

Bear in mind that the width and height settings are programatically assigned.

=item pblib_bar

A C

containing the whole progress bar, including any

accessories (such as the label). The only attribute used

by this module is C, which is set dynamically.

The rest is up to you. A good start is:

padding: 2 px;

border: solid black 1px;

text-align: center;

=item pblib_block_off, pblib_block_on

An individual block within the status bar. The following

attributes are set dynamically: C, C,

C.

=item pblib_number

Formatting for the C text (part of which is actually

an C element. C and C

are used here, and the whole appears centred within a C.

=cut

sub CGI::_pb_init {

5

16

my ($self, @crud) = CGI::self_or_default;

5

44

my $html = "";

# my $pb = $self->{progress_bar}[$#{$self->{progress_bar}}];

5

35

$self->{progress_bar}->{block_wi} = 1 if not $self->{progress_bar}->{block_wi} or $self->{progress_bar}->{block_wi} < 1 ;

5

45

$self->{progress_bar}->{layer_id} = {

container => 'pb_cont'.time,

form => 'pb_form'.time,

block => 'b'.time,

number => 'n'.time,

};

5

23

$self->CGI::_init_css;

5

18

$html .= "\n";

5

24

$html .= "\n" if $^W;

5

12

$html .= "\n

\n";

5

14

$html .= "\t\n\t

\n

" if $self->{progress_bar}->{label};
318
319	5					8	$html .= "\t \n\t";
320	5					11	foreach my $i (1 .. $self->{progress_bar}->{blocks}){
321	60					126	$html .= " ";
322							}
323	5					8	$html .= "\n\t\n";
324	5	50				15	$html .= "

325
326
327							/> / $self->{progress_bar}->{to}
328
329

" if $self->{progress_bar}->{label};

5

6

$html .= "\n";

5

20

$html .="\n\n" if $^W;

5

8

$html .= "\n\n";

5

77

return $html;

}

sub CGI::_init_css {

5

14

my ($self, @crud) = CGI::self_or_default;

5

67

$CSS = "

.pblib_bar {

border: 1px solid black;

padding: 1px;

background: white;

display: block;

text-align:left;

width: ".($self->{progress_bar}->{width})."px;

}

.pblib_block_on,

.pblib_block_off {

display: block;

".( $self->{progress_bar}->{orientation} eq 'vertical'?

"float:none;

width: 100%;

height: ".($self->{progress_bar}->{block_wi})."px;"

: "float:left;

width: ".($self->{progress_bar}->{block_wi})."px;"

)."

}

.pblib_block_off { border:1px solid white; background: white; }

.pblib_block_on { border:1px solid blue; background: navy; }

";

5

15

if ($self->{progress_bar}->{label}){

0

0

$CSS .=".pblib_number {

text-align: right;

border: 1px solid transparent;

}";

}

5

19

$self->{progress_bar}->{css} = $CSS;

}

=head1 BUGS, CAVEATS, TODO

=over 4

=item One bar per page

This may change.

=item Parameter passing doesn't match F

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

=item C not implimented

I'd like to see here something like the C;

not because I've ever used it, but because it might be cool.

=item 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 C<-label> might not look very nice

unless you did something quite fancy. So the next version (or so)

will support an C<-orientation> option.

=item Inline CSS and JS

Because it's easiest for me. I suppose some kind of over-loading of

the C would be possible, but then I'd have to check

it, and maybe update it, every time F was updated, which I

don't fancy.

=cut

1;

__END__