===========================================================
   A quick guide to implement an AJAX Progress Bar
===========================================================

IMPORTANT:
This guide will be only available with versions 2.3.0 alpha.
With final stable version 2.3.0, you can find this howto guide included
in The Definitive Guide. This last one will not be update until 2.3.0 (stable).


1. History
   All begun with Request #3985 (http://pear.php.net/bugs/bug.php?id=3985)
   posted on 2005-03-28.

   In 2005, I don't know yet AJAX, that I've learned only recently (end of
   year 2006). I've searched the most simple architecture that won't break
   current API, and gave immediat benefits for both PHP4 and PHP5 users.

   As there are many Ajax frameworks, I wouldn't imposed usage of one between
   many, and let free choice opened. So 2.3.0 alpha 1 will begin with a standard
   DOM XML Ajax driver. Later, others drivers (such as YUI, Prototype, ...),
   will be available and allow to use specifics features.

   While I didn't know HTML_AJAX, I've took a day to learn it, and I've begun
   to rewrite implementation of AJAX progress meter. Why this choice ? Because
   it's more easy to use either a simple asynchronous transfer with client and
   server, or have a combo with JS librairies such as Scriptaculous, YUI, ...
   And this with only one PEAR package (Special thanks to Joshua Eichorn, who
   made it possible).

   So alpha 2 and next versions (alpha, beta, stable) will come with
   HTML_AJAX 0.5.0 or better.

2. Design details

   Tracking the progress of a server-side operation by a client requires only
   one operation.
   A polling loop that will iterate one or more times until server task
   is completed (100%).
   This is done by JS function HTML_Progress2.statusCheck what will send
   periodically (update by interval; default is 2 seconds) a request to server
   either with :
   - class/method :
     HTML_Progress2.serverClassName, HTML_Progress2.serverMethodName
   - or simple php function :
     HTML_Progress2.serverCallback
   as callback.

   When the user-task is over and server return progress bar reach 100%
   (key: percentage, value: 100), client run function identified by
   HTML_Progress2.onComplete (default behavior is to reload the same page
   with query string "reload=true").

   If you want to change this behavior, you have just to change value of public
   HTML_Progress2.onComplete variable, and identify another function.
   See scriptaculous1 and scriptaculous2 examples

   Launching polling loop through asynchronous communication, is done by only
   one client action: run JS function  HTML_Progress2.start with identifier
   of progress bar (given by HTML_Progress2::getIdent), and with an optional
   latency (in millisecond) between two request calls.

2.1 Progress bar HTML design

    You can continue to use your old design built with versions 2.0.0 to 2.2.0,
    details are unchanged.

    Alpha 2 support now the multiple-labels system introduced with version 2.0.0

    See RequestStatus.class.php file, method getFullStatus() for a basic
    implementation example.

    You have just to return a key-value pair for each label identified at design
    level with a "labels" key array.
    <?php
    require_once 'HTML/Progress2.php';

    $pb = new HTML_Progress2();
    $pb->addLabel(HTML_PROGRESS2_LABEL_TEXT, 'txt2', 'caption ...');
    // label text identifier of "caption ..." is here: txt2
    ?>
    So if we want to change 'txt2' label value, at middle of progress (50%),
    we have to return an array with something like that:

    <?php
    // ...
    $status = array('percentage' => 50,
        'labels' => array('txt2' => 'half task done')
        );
    return $status;
    // ...
    ?>

    * IMPORTANT: ***************************************************************
    An (HTML_)AJAX server may be return label values that are unkown
    at design level. No error/warning will be raise !
    See RequestStatus.class.php file, getFullStatus() method, with this line
    <?php
    $this->status['labels']['txt4'] = 'Q4';
    ?>
    'txt4' label is undefined on all examples. But if in future we want to add
    a new text label, we just have to add it in design progress bar level, like
    this:
    <?php
    $pb->addLabel(HTML_PROGRESS2_LABEL_TEXT, 'txt4', 'Total tasks : ');
    ?>
    ****************************************************************************

2.2 Handle polling loop

    You are free to handle your user task as you want, but to refresh the
    progress meter status, you must at least return an array with the key
    "percentage" that identify the new value (from 0 to 100) of progress.

    You can also return some new label values. You don't have to return all
    label defined if you want to change only one.

    See RequestStatus.class.php file, getFullStatus() method for sample of an
    implementation.


2.3 Refreshing progress bar

    Highlight cells is still done by default progress javascript code
    See: HTML_Progress::getScript(), or external file "HTML_Progress2.js",
    HTML_Progress2.refresh function.

    Callback run by HTML_AJAX is HTML_Progress2.statusCheckCallback

    Server script should return a result object with at least the 'percentage'
    property defined. 'labels' is optional.


3. Roadmap

   Alpha 1 :
   - DO NOT support indeterminate mode
   - DO NOT support progress bar with labels

   Alpha 2 :
   - back to old owner implementation of AJAX, and used now the HTML_AJAX package
   - add support of multiple labels system

   Stable :
   - The Definitive Guide will include these informations and your comments


4. Appendixes

   See also examples
   PEAR/docs/HTML_Progress2/examples/ajax/default1.php
   PEAR/docs/HTML_Progress2/examples/ajax/default2.php
   PEAR/docs/HTML_Progress2/examples/ajax/default3.php
   PEAR/docs/HTML_Progress2/examples/ajax/scriptaculous1.php
   PEAR/docs/HTML_Progress2/examples/ajax/scriptaculous2.php

