****************************
 The HTML_Progress2 Package
****************************

---------------------------------------------
 User Documentation - Migration to version 2
---------------------------------------------

:Author:        Laurent Laville
:Contact:       pear@laurent-laville.org
:Date:          $Date: 2005/06/23 14:34:36 $
:Revision:      $Revision: 1.2 $


Table of contents

1. Intended audience
2. Why these changes ?
3. How to adjust your code
4. Multiple label system

*******************************

1. Intended audience
====================

If you have not already used HTML_Progress 1.x, this guide is not for you. It
was written to help users to migrate easily all their scripts from version
1.x to the major 2.0.0.


2. Why these changes ?
======================

HTML_Progress2 has improved a lot since HTML_Progress 1.2.x.
With merges of secondary classes (UI and DM) to the main core class, i've
removed duplicates methods and unified API.

With the addition of a new plugin error management, it was the first milestone
to have a version a bit less dependent to PEAR.
Lot of users are afraid to install a such framework on their system, for many
reasons. So second milestone and goal, was to create a new class much lighter
and without any dependencies to a such audience: HTML_Progress2_Lite was born.

The HTML_Progress2_Lite class does not allows to do all that is possible with
HTML_Progress2 class. See progress2LiteGuide for a features comparative.

And last but not least, a multiple labels system was introduced, that give
ability to have more than just one percent text information or one custom text
label.


What was removed ?
------------------
Very few features was removed during this merges :

- setModel API
- ability to extends UI class to make custom user interface
- ability to extends DM class to make custom data management interface
- isStringPainted API (due to new multiple label system)
- setStringPainted API (due to new multiple label system)
- setStringAttributes API, replaced by setLabelAttributes API
  = > see new multiple label system chapter.
- getString API (due to new multiple label system)
- setString API replaced by addLabel() method
- HTML_PROGRESS_ERRORSTACK_* and HTML_PROGRESS_LOG_TYPE_* constants
  = > see errorHandlerGuide


3. How to adjust your code
==========================

Core related
------------
 * class constructor
   HTML_Progress 1.x allows multiple signatures (5); HTML_Progress2 allows
   one unique signature even if all parameters are optional.

   Resume of HTML_Progress 1.x signatures :
   1.  $bar = new HTML_Progress();
   2.  $bar = new HTML_Progress($orient);
   3.  $bar = new HTML_Progress($min, $max);
   4.  $bar = new HTML_Progress($orient, $min, $max);
   5.  $bar = new HTML_Progress($model);

   Signature #5 is no more allowed because feature was removed.

   HTML_Progress2 signature :
       $bar = new HTML_Progress2($errorPrefs, $orient, $min, $max, $percentLabel);

       $errorPrefs   :hash of options to configure the API error handling system
                      default is empty array (use PEAR_Error object)
                      = > see errorHandlerGuide
       $orient       :orientation of the progress bar (see constants)
       $min          :minimum value of the progress bar (default is zero)
       $max          :maximum value of the progress bar (default is 100)
       $percentLabel :progress bar percent label identifier (default is 'pct1')


 * apiVersion()
   Returns the current API version compatible with php.version_compare()

   This API returns now a string rather than a float, and allows a largest
   version naming (such as x.y.zRCn)


 * getPercentComplete()
   Returns the percent complete for the progress bar

   This API has now an optional parameter that allows to return either
   - a float by default (range 0.00 to 1.00)
   - an integer (range 0 to 100).


 * display()
   Renders the new value of progress bar.

   This API has a new behaviour. It will now send only toHtml() output
   to browser, while in previous version this api managed browser refresh.

   Refresh are now made by the moveNext() or moveStep() API.


User interface related
----------------------
 * setCellCount()
   Sets the number of cell in the progress bar

   This API accept now zero as minimum value for smooth progress meter.
   That means that a progress bar with zero cell, will render a full bar
   as HTML_Progress2_Lite do.


 * setLabelAttributes()
   Sets a label attributes

   With HTML_Progress 1.x you might only defines one custom text label.
   Now with new multiple label system you can do it at infinite. There is
   no label number limit (except memory).

   You have to defines first each label you will put around the progress bar
   by the addLabel() method, before to set its attributes.

   With Progress 1.x, you could have a script like this:
   ::
    <?php
    require_once 'HTML/Progress.php';

    $bar = new HTML_Progress();
    $bar->setAnimSpeed(100);
    $bar->setIncrement(5);
    $bar->setStringPainted(true);          // get space for the string
    $bar->setString('');                   // but don't paint it

    $ui =& $bar->getUI();
    $ui->setStringAttributes('width=350 align=left');
    // ....
    ?>
   ::
   which prepare to render a custom string on right side of the progress bar.

   Now with Progress2, you will have a modified script like:
   ::
    <?php
    require_once 'HTML/Progress2.php';

    $bar = new HTML_Progress2();
    $bar->setAnimSpeed(100);
    $bar->setIncrement(5);
    $bar->addLabel(HTML_PROGRESS2_LABEL_TEXT, 'txt1', 'Simple static text');
    $bar->setLabelAttributes('txt1', array(
        'valign' => 'top',
        'left' => 0
    ));
    // ....
    ?>
   ::

   The percent info will be render alone at right side of the progress bar
   (default) and we have added a static text label on top side of the same
   progress bar.
   = > See multiple label system chapter for advanced explanations.


Data management related
-----------------------
 * moveNext()
   Changes value of the progress bar to the next step

   This NEW API was introduced with the new multiple label system, and should
   replaced incValue() deprecated.

   So if you have a script like this one:
   ::
    <?php
    require_once 'HTML/Progress.php';

    $bar = new HTML_Progress();
    $bar->setAnimSpeed(100);
    ?>
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
        "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
    <head>
    <style type="text/css">
    <!--
    <?php echo $bar->getStyle(); ?>
    // -->
    </style>
    <script type="text/javascript">
    <!--
    <?php echo $bar->getScript(); ?>
    //-->
    </script>
    </head>
    <body>
    <?php
    echo $bar->toHtml();
    do {
        $bar->display();    // <--- to remove !!!
        if ($bar->getPercentComplete() == 1) {
            break;
        }
        $bar->sleep();
        // your long process goes here !
        $bar->incValue();   // <--- to replace !!!
    } while(1);
    ?>
    </body>
    </html>
   ::

   Notice the process loop; You should replace $bar->incValue()
   by $bar->moveNext(), and remove $bar->display().

   Of course, if you used the run() method instead of the loop, you have
   nothing to change.


 * moveStep()
   Changes new step value of the progress bar.

   This NEW API change internal value of the progress bar and refresh
   browser output. Should replaced old api setValue() that still exists.
   Main reason is behaviour change of display() method.


4. Multiple label system
========================

One of the major changes in HTML_Progress version 2 is ability to add more
than just one text zone information floating around the progress bar.

To do this, they were BC and behaviour changes with old API display(), and
incValue().

IMPORTANT:  display() must now be used only once, to send html code
            to your browser.

            moveNext(), or moveStep() should replace incValue() and setValue()
            because they manage the render refresh.

To add a new label floating around the progress meter, you must :

1. defines the label with addLabel() method that accept 3 parameters
   *type  :label category (see constants HTML_PROGRESS2_LABEL_*)
           HTML_PROGRESS2_LABEL_TEXT = a static text
           HTML_PROGRESS2_LABEL_BUTTON = a form button
           HTML_PROGRESS2_LABEL_STEP = a step indicator such as 10/100
           HTML_PROGRESS2_LABEL_PERCENT = current percent information
           HTML_PROGRESS2_LABEL_CROSSBAR = a little animation
   *name  :unique label identifier
   *value :optional (default is '&nbsp;')

2. sets its attributes (render) with setLabelAttributes() method
   that accept 2 parameters
   *name       :label identifier (the same sets with addLabel() method)
   *attributes :associative array or string of HTML tag attributes

For example we could have a script like that:
   ::
    <?php
    require_once 'HTML/Progress2.php';

    $pb = new HTML_Progress2();
    $pb->setAnimSpeed(300);
    $pb->setIncrement(10);

    // Adds additional labels
    $pb->addLabel(HTML_PROGRESS2_LABEL_TEXT, 'txt1', 'Fire at will');

    $pb->addLabel(HTML_PROGRESS2_LABEL_CROSSBAR, 'crs1');
    $pb->setLabelAttributes('crs1', array(
        'valign' => 'top',
        'align'  => 'center',
        'width'  => 170,
        'color'  => 'blue'
    ));

    $pb->addLabel(HTML_PROGRESS2_LABEL_STEP, 'stp1');
    $pb->setLabelAttributes('stp1', array(
        'valign' => 'bottom',
        'color'  => 'blue'
    ));

    $pb->addLabel(HTML_PROGRESS2_LABEL_BUTTON, 'btn1', 'Run again');
    $pb->setLabelAttributes('btn1', array(
        'width' => 100,
        'top' => 0,
        'color' => 'red'
    ));
    // ....
    ?>
   ::


HTML_PROGRESS2_LABEL_TEXT attributes reference
----------------------------------------------

   +-----------------------------------------------+------------------------+
   | Attributes                                    |    Default values      |
   +===============================================+========================+
   | left                                          |        5               |
   +-----------------------------------------------+------------------------+
   | top                                           |        5               |
   +-----------------------------------------------+------------------------+
   | width                                         |        0               |
   +-----------------------------------------------+------------------------+
   | height                                        |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        left            |
   +-----------------------------------------------+------------------------+
   | valign (top, bottom, left, center, right)     |        top             |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+
   | class (1)                                     |   progressTextLabel%s  |
   +-----------------------------------------------+------------------------+

   Note (1): the %s will be replace by the progress meter identifier
             = > see API getIdent(), setIdent()


HTML_PROGRESS2_LABEL_BUTTON attributes reference
------------------------------------------------

   +-----------------------------------------------+------------------------+
   | Attributes                                    |    Default values      |
   +===============================================+========================+
   | action                                        |                        |
   +-----------------------------------------------+------------------------+
   | target                                        |        self            |
   +-----------------------------------------------+------------------------+
   | left                                          |        0               |
   +-----------------------------------------------+------------------------+
   | top                                           |        5               |
   +-----------------------------------------------+------------------------+
   | width                                         |        0               |
   +-----------------------------------------------+------------------------+
   | height                                        |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        center          |
   +-----------------------------------------------+------------------------+
   | valign (top, bottom, left, center, right)     |        bottom          |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+
   | class (1)                                     | progressButtonLabel%s  |
   +-----------------------------------------------+------------------------+

   Note (1): the %s will be replace by the progress meter identifier
             = > see API getIdent(), setIdent()


HTML_PROGRESS2_LABEL_STEP attributes reference
----------------------------------------------

   +-----------------------------------------------+------------------------+
   | Attributes                                    |    Default values      |
   +===============================================+========================+
   | left                                          |        5               |
   +-----------------------------------------------+------------------------+
   | top                                           |        5               |
   +-----------------------------------------------+------------------------+
   | width                                         |        165             |
   +-----------------------------------------------+------------------------+
   | height                                        |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        right           |
   +-----------------------------------------------+------------------------+
   | valign (top, bottom, left, center, right)     |        top             |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+
   | class (1)                                     |  progressStepLabel%s   |
   +-----------------------------------------------+------------------------+

   Note (1): the %s will be replace by the progress meter identifier
             = > see API getIdent(), setIdent()


HTML_PROGRESS2_LABEL_PERCENT attributes reference
-------------------------------------------------

   +-----------------------------------------------+------------------------+
   | Attributes                                    |    Default values      |
   +===============================================+========================+
   | left                                          |        5               |
   +-----------------------------------------------+------------------------+
   | top                                           |        5               |
   +-----------------------------------------------+------------------------+
   | width                                         |        50              |
   +-----------------------------------------------+------------------------+
   | height                                        |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        right           |
   +-----------------------------------------------+------------------------+
   | valign (top, bottom, left, center, right)     |        right           |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+
   | class (1)                                     | progressPercentLabel%s |
   +-----------------------------------------------+------------------------+

   Note (1): the %s will be replace by the progress meter identifier
             = > see API getIdent(), setIdent()


HTML_PROGRESS2_LABEL_CROSSBAR attributes reference
--------------------------------------------------

   +-----------------------------------------------+------------------------+
   | Attributes                                    |    Default values      |
   +===============================================+========================+
   | left                                          |        5               |
   +-----------------------------------------------+------------------------+
   | top                                           |        5               |
   +-----------------------------------------------+------------------------+
   | width                                         |        20              |
   +-----------------------------------------------+------------------------+
   | height                                        |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        center          |
   +-----------------------------------------------+------------------------+
   | valign (top, bottom, left, center, right)     |        right           |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+
   | class (1)                                     | progressCrossbarLabel%s|
   +-----------------------------------------------+------------------------+

   Note (1): the %s will be replace by the progress meter identifier
             = > see API getIdent(), setIdent()