PEAR Progress2 logo

HTML_Progress2 : The Definitive Guide

Chapter 5. Quick Start with HTML_Progress2
Prev  Part II. Getting Started  Next

Chapter 5. Quick Start with HTML_Progress2

Table of Contents

Designing
Shape
Cells
Border
Background
Fill direction
Processing
With a user callback
Without user callback
Strategy of handling
Strategy 1: moveNext
Strategy 2: moveStep

Start using HTML_Progress2 straight away.

Through samples code that are possible real cases we will study all features of the HTML_Progress2 package. Additional tutorials will help you to learn what are others features: Indeterminate Mode, Listener, Monitoring, Generator interactive tools.

There are two main phases in developement and use of a progress meter: designing and processing.

Designing

Shape
Cells
Border
Background
Fill direction

You have probably your ideas of what it should look like: shape, size, colors. So how to build it ?

Shape

Even if it's not yet ready to be display, following source code will create a new instance of the HTML_Progress2 class that is ready to build an horizontal (default shape) progress bar:

  1. <?php
  2. require_once 'HTML/Progress2.php';
  3.  
  4. $pb = new HTML_Progress2();
  5. ?>

If you want to build others shapes like :

  • vertical progress bar, use constant HTML_PROGRESS2_BAR_VERTICAL
  • square or rectangle, use constant HTML_PROGRESS2_POLYGONAL
  • circle or ellipse, use constant HTML_PROGRESS2_CIRCLE
  1. <?php
  2. require_once 'HTML/Progress2.php';
  3.  
  4. $pb = new HTML_Progress2();
  5. $pb->setOrientation(HTML_PROGRESS2_BAR_VERTICAL);
  6. ?>

Only with horizontal and vertical progress bar, you have ability to choose between smooth or cell rendering. What is it ?

A smooth progress bar is a full bar that look like this:

while cell progress bar look like :

Remember that default progress meter is horizontal progress bar with ten cells (as above). If you want to have smooth progress bar, or change cell spacing (in pixel), use the setCellAttributes() method with spacing attribute.

  1. <?php
  2. require_once 'HTML/Progress2.php';
  3.  
  4. $pb = new HTML_Progress2();
  5. $pb->setCellAttributes('spacing=0');
  6. ?>
[Note] Note
it's not a real smooth progress meter as HTML_Progress2_Lite can do.

Cells

By default, an horizontal or vertical (and even circle/ellipse) progress meter have ten cells, one for each ten percent.

Among attribute you can change there are: size (height, width) and color(active inactive). See setCellAttributes() method for all details and default values.

We can also enlarge or reduce the cell count of the progress bar with the setCellCount() method.

If we want to have a twelve cells horizontal progress meter with largest square (20x20 pixels) and red skin, then write :

  1. <?php
  2. require_once 'HTML/Progress2.php';
  3.  
  4. $pb = new HTML_Progress2();
  5. $pb->setCellCount(12);
  6. $pb->setCellAttributes(array(
  7.     'active-color' => '#FF0000',
  8.     'inactive-color' => '#FF9900',
  9.     'width' => 20,
  10.     'height' => 20,
  11.     'spacing' => 4
  12. ));
  13. ?>
[Note] Note
You can also use an html string that defines attributes list. In our sample we will write:
  1. <?php
  2. $pb->setCellAttributes('active-color=#FF0000 inactive-color=#FF9900 width=20 height=20 spacing=4');
  3. ?>

Border

A progress bar (horizontal or vertical) can be surrounded by a border (it's not the default).

  1. <?php
  2. require_once 'HTML/Progress2.php';
  3.  
  4. $pb = new HTML_Progress2();
  5. $pb->setBorderPainted(true);
  6. $pb->setBorderAttributes(array(
  7.     'width' => 2,
  8.     'style' => 'solid',
  9.     'color' => 'red'
  10. ));
  11. ?>

Partial script above, will produce an horizontal progress bar with a red solid border; something like this:

[Important] Important
Without setBorderPainted() method and a TRUE argument, there won't be any border rendering. Even if you set a positive width with setBorderAttributes() method.

Background

A progress bar (horizontal or vertical) has a white background by default, but you can change that. You may even use an image as background. Don't worry if image is smaller (use background-repeat attribute) or bigger than progress meter. Accuracy positionning is possible with usage of background-position attribute.

  1. <?php
  2. require_once 'HTML/Progress2.php';
  3.  
  4. $pb = new HTML_Progress2();
  5. $pb->setProgressAttributes(array(
  6.     'background-color' => '#339900',
  7.     'background-image' => 'degrade.jpg',
  8.     'background-repeat' => 'repeat-y'
  9. ));
  10. $pb->setCellAttributes('inactive-color=transparent');
  11. ?>
[Tip] Tip
Even if you want to use an image as background, don't forget to add background-color attribute as an alternative.

It's same feature as img tag for html and its alt attribute.

Fill direction

Progress meter can be fill in two directions (ways) called natural or reverse. Default behavior is natural fill.

  • For horizontal progress bar, natural way is from left to right, while reverse way is from right to left.

  • For vertical progress bar, natural way is from down to up, while reverse way is from up to down.

  1. <?php
  2. require_once 'HTML/Progress2.php';
  3.  
  4. $pb = new HTML_Progress2();
  5. $pb->setOrientation(HTML_PROGRESS2_BAR_VERTICAL);
  6. $pb->setFillWay('reverse');
  7. $pb->setAnimSpeed(50);
  8. $pb->setCellCount(15);
  9. $pb->setCellAttributes('active-color=#970038 inactive-color=#FFDDAA width=50 height=13');
  10. $pb->setBorderPainted(true);
  11. $pb->setBorderAttributes('width=1 color=#000000');
  12. $pb->setLabelAttributes('pct1', array(
  13.     'font-size' => 8,
  14.     'color' => '#FF0000',
  15.     'background-color' => '#C3C6C3',
  16.     'align' => 'center',
  17.     'valign' => 'bottom'
  18. ));
  19. ?>

Partial script above, will produce a vertical progress bar filled in reverse way (top to down), that look like:

HTML_Progress2 : The Definitive Guide v 2.4.0 : April 20, 2007
Prev  Up  Next
Chapter 4. Introduction  Home  Processing