PEAR Progress2 logo

HTML_Progress2 : The Definitive Guide

Chapter 14. New Features in HTML_Progress2
Prev  Part III. Migrating Guide  Next

Chapter 14. New Features in HTML_Progress2

Table of Contents

Multiple Label System
Add a new label
Remove existing label
Error Handling
Reuse CSS
Step 1 : Extract Javascript code
Step 2 : Extract CSS code
Step 3 : Remove HTML_Progress2 css properties
Step 4 : Adjust CSS class selector
Step 5 : play with new pattern

This chapter documents all of the differences between HTML_Progress 1.x and the new features introduced in HTML_Progress2.

The most significant change in HTML_Progress2 is the addition of the Multiple Label System.

Multiple Label System

Add a new label
Remove existing label

While with HTML_Progress 1.x you have no choice, or so few, to display informations with text zone also called “string”; In the new API of HTML_Progress2 you may have as much labels as you want all around the progres meter.

No need anymore to do a choice between the percent text info and captions while the progress meter reach particular values. You can have both at same time, and even more.

As in previous version, HTML_Progress 1.x, you can have text zone as label, but also now four more types. Here are the list :

(text) HTML_PROGRESS2_LABEL_TEXT

A simple text zone

(button) HTML_PROGRESS2_LABEL_BUTTON

A simple button

(step) HTML_PROGRESS2_LABEL_STEP

A step zone information to display value of current moveStep()

(percent) HTML_PROGRESS2_LABEL_PERCENT

The basic percent text information formatted as “67 %”.

(crossbar) HTML_PROGRESS2_LABEL_CROSSBAR

A little javascript cross rotate animation

Add a new label

The only label you don't have to set, in most cases, with addLabel() method is the percent text info, identified by pct1 by default.

[Note] Note
You can remove the percent text info at build time with the HTML_Progress2 class construtor and the fifth parameter set to FALSE.
  1. <?php
  2. $bar = new HTML_Progress2($errorPrefs, $orient, $min, $max, $percentLabel);
  3. /*
  4.        $errorPrefs   :hash of options to configure the API error handling system
  5.                       default is empty array (use PEAR_Error object)
  6.        $orient       :orientation of the progress bar (see constants)
  7.        $min          :minimum value of the progress bar (default is zero)
  8.        $max          :maximum value of the progress bar (default is 100)
  9.        $percentLabel :progress bar percent label identifier (default is 'pct1')
  10.  */
  11. ?>
In such condition, if you need after a while to display the percent text again, you shall use the addLabel() method with any free identifier (can be pct1 as any other else).

Goal of this mini tutorial is to build a horizontal progress bar with percent text info on right side, with four other kind of label (text, crossbar, step, button). Something like that :

For a full source code, have a look here.

No special difficulty. We will used four times the couple :

  1. <?php
  2. $bar->addLabel($type, $name, $value);
  3. /*
  4.        $type         :label type / a constant HTML_PROGRESS2_LABEL_* value
  5.        $name         :label name (identifier)
  6.        $value        :initial label value
  7.  */
  8.  
  9. $bar->setLabelAttributes($name, $attributes)
  10. /*
  11.        $name         :label name (identifier)
  12.        $attributes   :associative array or string of HTML tag attributes
  13.  */
  14. ?>

With $bar an instance of HTML_Progress2 object.

  1. <?php
  2. $bar = new HTML_Progress2();
  3. ?>

For a full attributes list depending of each label kind, see the Reference Guide, setLabelAttributes() related.

Remains of the script is as usal:

  • complete build of the progress meter (css, js, html parts) : getStyle(), getScript(), display()
  • see the progress meter in action : run()

Remove existing label

This feature is available at build-time, and may be usefull to extend some progress meter from a common source, and remove the unnecessary labels.

For example, if you consider the previous script, as your common/core script, written in two parts/templates (build-meter.php, run-meter.php) splitted at the DTD frontier.

So, if you want to build a new progress meter without the button. You have just to re-used your previous code and complete with :

  1. <?php
  2. include_once 'build-meter.php';
  3.  
  4. $pb->removeLabel('btn1');
  5.  
  6. include_once 'run-meter.php';
  7. ?>

Pretty easy.

HTML_Progress2 : The Definitive Guide v 2.4.0 : April 20, 2007
Prev  Up  Next
Data Management related  Home  Error Handling