Table of Contents

Intended Audience

This document is written as a guide to and reference for the HTML_Progress package, for both beginner and expert users.

Why use HTML_Progress ?

There are some classes that exists, but never none of them as such degree of customization. You can produce all kind of progress indicator you want: from basic horizontal bar, vertical bar, to circle, ellipse, and even free polygonal shape.

Features

• create horizontal, vertival bar and also circle, ellipse and polygons (square, rectangle)
• allows usage of existing external StyleSheet and/or JavaScript
• all elements (progress, cells, string) are customizable by their html properties
• percent/string is floating all around the progress meter
• compliant with all CSS/XHMTL standards
• integration with all template engines is very easy
• implements Observer design pattern. It is possible to add Listeners
• adds a customizable UI monitor pattern to display a progress bar. User-end can abort progress at any time.
• Look and feel can be sets by internal API or external config file
• Allows many progress meter on same page without uses of iframe solution
• HTML_Progress 1.2.0 works with PHP 5

Pre-requisites

It is assumed that you have installed both PHP and PEAR, and that you have rudimentary knowledge of PHP, HTML and JavaScript. If you are not a PEAR user, don't worry you may use HTML_Progress since 1.2.0 without a PEAR installation, with some features restrictions. See Appendix A. Installation for details.

It is also assumed that your PHP scripts are correctly interpreted by your web server. In most case it will be probably Apache, but you may also have IIS. HTML_Progress runs both on Windows and *nix.

What is new ?

First publish release of HTML_Progress on PEAR website was on August 1st, 2003. Its introduced the first attempt of stable API version. But as i wanted HTML_Progress more open to future evolutions, i've redevelopped a second API more robust. So versions 0.4.x, 0.5.x and 0.6.x are all incompatible with the new API introduced first in version 1.0

• 2003-11-16 (version 1.0)

  First attempt to:

  • create a Progress Monitor solution.
  • interactive tools to build progress bar (Progress Maker).

• 2004-02-14 (version 1.1)
  • Second version of Progress Monitor, using the QuickForm rendering system.
  • Progress Uploader was born: a web-ftp file uploads solution.
  • Progress Generator became the next generation of Progress Maker.

• 2004-09-12 (version 1.2.0)
  • new shapes such as circle, ellipse, square, rectangle are allowed.
  • error plugin architecture to allows all error handler you might want.
  • Progress Uploader was removed
  • HTML_Progress_Model class was removed, but feature still exist.

Package Overview

HTML_Progress provides seven classes to help you use progress bars:

Global classes

• HTML_Progress

  Main component to graphically display how much of a total task has completed. See (Using Determinate Progress Bars) for information and an example of using a typical progress bar. The section indeterminate.pkg tells you how to animate a progress bar to show activity before the task's scope is known.

Data Model class

• HTML_Progress_DM

  This class handles any mathematical issues arising from assigning faulty values.

User Interface classes

• HTML_Common

  This class provides methods for html code display and attributes handling. It is a base class for other HTML classes and can be downloaded at PEAR under HTML_Common package.

• HTML_Progress_UI

  This class provides a basic look and feel implementation of a progress bar.

• HTML_Progress_Generator

  This class provides an easy way to build and run demo of your own progress bar. You can also save final PHP and/or CSS source-code. HTML_Progress_Generator become the next generation of interactive tools after ProgressMaker (included in HTML_Progress 1.0)

Observers classes

• HTML_Progress_Observer

  This class implements the observer pattern for watching progress bar activity and taking actions on exceptional events.

• HTML_Progress_Monitor

  This class allow an easy way to display progress in a dialog. The user can cancel the task. It requires another PEAR package, the HTML_QuickForm package which provides methods for creating, validating, processing HTML forms.

Getting this documentation

In the HTML_Progress 1.2.0 bundle you will find a windows help file (chm) and also a portable document file (pdf) reading by acrobat reader.

You may also read this Definitive Guide online in HTML format at http://pear.laurent-laville.org/HTML_Progress/apidoc/HTML/.

Getting examples

All of these documentation examples are included into the HTML_Progress package bundle. You can get the most up-to-date examples from the web site: http://pear.laurent-laville.org/HTML_Progress/examples/