A little tutorial/howto for HTML_Progress

July 23,2003

By Laurent Laville

Table of Contents

  1. What does it ?
  2. How to get it
  3. API-Documentation
  4. How to use it
  5. More on subject
  6. The End

  1. What does it ?

    It just put an horizontal loading bar on XHTML document of your choice, and allows user to wait and see progress status during a long procedure such an installation. You get a more or less decent result with just the basic settings, but it's also highly configurable, so you can almost get what you want. See below for some real examples and how to configure look and feel of loading bar ...
  2. How to get it

    The recommended way is to use the pear-installer and then type
    pear install HTML_Progress-0.4.1.tgz 
    
    (the pear installer should be installed by default with PHP 4.3) But you can also get the class directly from my website (
    http://farell.free.fr/en/pear/bin/HTML_Progress-0.4.1.tgz)
  3. API-Documentation

    HTML format generated with phpDocumentor 1.2.1
  4. How to use it

    Prerequisites

    You need to have 2 classes installed before to use HTML_Progress package.
    • HTML_CSS is a class for generating CSS declarations
    • HTML_Page package provides a simple interface for generating an XHTML compliant page

    Where to get ressources needed

    Even if it's still in beta state (2.0.0b5 on 2003-07-29) you can get the HTML_Page's class directly from the pear website
    (
    http://pear.php.net/package-info.php?package=HTML_Page).

    You can get the HTML_CSS's class directly from the pear website
    (http://pear.php.net/package-info.php?package=HTML_CSS).

    Author of these both classes is Klaus Gunther. Thanks to him to help me to make my dream a reality !

    The most simple example

    Let's start with the most simple example. No configuration, use default values as below:
        *	width                   180px
        *	height                   22px
        *	background-color        white
        *	padding                   2px
        *	border-width              0px
        *	border-style            solid
        *	border-color            black
        *	cell-width               15px
        *	cell-height              20px
        *	cell-spacing              2px
        *	active-color          #006600
        *	inactive-color        #cccccc
    
    progress1.php

    <?php

    require_once ('HTML/Progress.php');

    $pkg = array('PEAR', 'Archive_Tar', 'Config',
        
    'HTML_QuickForm', 'HTML_CSS', 'HTML_Page', 'HTML_Progress', 'HTML_Template_Sigma',
        
    'Log', 'MDB', 'PHPUnit');

    $bar = new HTML_Progress();

    for (
    $i=0; $i<11; $i++) {
        
    $bar->display(10);
        echo
    "installing package ... : ". $pkg[$i] ."<br /> \n";
    }

    ?>
    This example will produce :   

    Add text percent info on right side

    In this example, we introduce capability to include the loading bar into an existing XHTML document. We use the HTML_Page class to make it easy.
    When we create new instance of HTML_Progress, we give reference address of existing page (see HTML_Page instance) and we also re-size width of loading bar (230 pixels) to allow text percent info seeing perfectly.
    We activate the text display with line below, and give to text a font-size of 14 pixels.
    $bar->setText(true, array('size' => '14px'));
    
    progress2.php

    <?php

    require_once ('HTML/Progress.php');

    $p = new HTML_Page();
    $p->setTitle("PEAR::HTML_Progress - Example 2");
    $p->setMetaData("author", "Laurent Laville");

    $bar = new HTML_Progress(&$p, array('width' => '230px'));
    $bar->setText(true, array('size' => '14px'));

    $css =& $bar->getStyle();
    $css->setStyle('body', 'background-color', '#444444');
    $p->addStyleDeclaration(&$css);
    $p->addBodyContent($bar->toHTML());
    $p->display();

    for (
    $i=0; $i<11; $i++) {
    /*  You have to do something here  */
        
    $bar->display(10);
    }

    ?>
    This example will produce :   

    Change each color elements

    Based on previous example, this one allow more redefines on each element's colors.
    For list of key value available, see
    The most simple example.
    progress3.php

    <?php

    require_once ('HTML/Progress.php');

    $p = new HTML_Page();
    $p->setTitle("PEAR::HTML_Progress - Example 3");
    $p->setMetaData("author", "Laurent Laville");

    $layout = array(
        
    'width'         => '200px',
        
    'border-width'  => '1px',
        
    'border-color'  => 'navy',
        
    'cell-width'    => '10px',
        
    'active-color'  => '#3874B4',
        
    'inactive-color'=> '#EEEECC'
    );

    $bar = new HTML_Progress(&$p, $layout);
    $bar->setText(true, array('size' => '14px'));

    $css =& $bar->getStyle();
    $css->setStyle('body', 'background-color', '#eeeeee');
    $p->addStyleDeclaration(&$css);
    $p->addBodyContent($bar->toHTML());
    $p->display();

    for (
    $i=0; $i<11; $i++) {
    /*  You have to do something here  */
        
    $bar->display(16);
    }

    ?>
    This example will produce :   

    Another color configuration

    In this example we give to text info a new font-size but also a new color(red). Here is the code :
    $bar->setText(true, array('size' => '14px', 'color' => 'red'));
    
    progress4.php

    <?php

    require_once ('HTML/Progress.php');

    $layout = array(
        
    'width'         => '300px',
        
    'border-width'  => '1px',
        
    'cell-width'    => '20px',
        
    'active-color'  => '#970038',
        
    'inactive-color'=> '#FFDDAA'
    );

    $bar = new HTML_Progress(false, $layout);
    $bar->setText(true, array('size' => '14px', 'color' => 'red'));

    for (
    $i=0; $i<11; $i++) {
    /*  You have to do something here  */
        
    $bar->display(10);
    }

    ?>
    This example will produce :   

    A plain loading bar, no more 10 cells

    Again a new presentation, with this time a plain loading bar. We can do it so easy, but changing only one value:
    'padding'           => '0px',
    
    Default 2px make a 10 cells look and feel !
    progress5.php

    <?php

    require_once ('HTML/Progress.php');

    $p = new HTML_Page();
    $p->setTitle("PEAR::HTML_Progress - Example 5");
    $p->setMetaData("author", "Laurent Laville");


    $layout = array(
        
    'width'             => '300px',
        
    'background-color'  => '#EBEBEB',
        
    'padding'           => '0px',
        
    'border-width'      => '1px',
        
    'border-style'      => 'inset',
        
    'border-color'      => 'white',
        
    'cell-width'        => '20px',
        
    'cell-spacing'      => '0px',
        
    'active-color'      => '#000084',
        
    'inactive-color'    => '#3A6EA5'
    );

    $bar = new HTML_Progress(&$p, $layout);
    $bar->setText(true);

    $css =& $bar->getStyle();
    $css->setStyle('body', 'background-color', '#c3c6c3');
    $css->setStyle('body', 'font-family', 'Verdana, Arial');
    $p->addStyleDeclaration(&$css);
    $p->addBodyContent($bar->toHTML());
    $p->display();


    /*  Progress Start */
    echo "task to do at start  ... <br /> \n";
    $bar->display(0,"set");

    /*  You have to do something here at 25% */
    echo "task to do at 25%  ...   <br /> \n";
    sleep(1);
    $bar->display(25,"set");

    /*  You have to do something here at 50% */
    echo "task to do at 50%  ...   <br /> \n";
    sleep(1);
    $bar->display(50,"set");

    /*  You have to do something here at 75% */
    echo "task to do at 75%  ...   <br /> \n";
    sleep(1);
    $bar->display(75,"set");

    /*  Progress End */
    echo "it's finished: hope you've enjoy it ! ";
    sleep(1);
    $bar->display(100,"set");

    ?>
    This example will produce :   

    Integration with template engine

    Here is an example of Sigma template engine integration with the famous HTML_QuickForm package.
    progress6.php

    <?php

    require_once ('HTML/QuickForm.php');
    require_once (
    'HTML/QuickForm/Renderer/ITStatic.php');
    require_once (
    'HTML/Template/Sigma.php');
    require_once (
    'HTML/Progress.php');


    $tpl = new HTML_Template_Sigma('.');
    $tpl->loadTemplateFile('installing.html');
            
    $vars = array (    
        
    "L_SETUP_APP_TITLE"    => "SW4P",
        
    "L_APPNAME"            => "My Template Sample",
        
    "L_APPCOPYRIGHT"       => "&copy 2003 SW4P Team "
    );
    $tpl->setVariable($vars);

    $form = new HTML_QuickForm('form');
    $form->addElement('button', 'cancel', 'Cancel', 'style="width:100px;" disabled="true"');

    $layout = array(
        
    'width'            => '200px',
        
    'border-width'     => '2px',
        
    'border-color'     => '#7B7B88',
        
    'cell-width'       => '10px',
        
    'active-color'     => '#7B7B88',
        
    'inactive-color'   => '#D0D0D0'
    );

    $p = new HTML_Page();
    $p->setTitle("PEAR::HTML_Progress - Example 6");
    $p->setMetaData("author", "Laurent Laville");
    $p->addStyleSheet("./styles.css");


    $bar = new HTML_Progress(&$p, $layout);
    $bar->setText(true);

    $tpl->setVariable("L_PROGRESS_BAR", $bar->toHTML());

    $renderer =& new HTML_QuickForm_Renderer_ITStatic($tpl);
    $form->accept($renderer);

    $css =& $bar->getStyle();
    $css->setStyle('body', 'background-color', '#444444');
    $p->addStyleDeclaration(&$css);
    $p->addBodyContent($tpl->get());
    $p->display();

    for (
    $i=0; $i<11; $i++) {
    /*  You have to do something here  */
        
    $bar->display(10);
    }

    ?>
    This example will produce :   

    We can also use a pre-set stylesheet for Progress layout. Here is how to do :

    Remove line:
    $layout = array( 
        'width'            => '200px', 
        'border-width'     => '2px', 
        'border-color'     => '#7B7B88', 
        'cell-width'       => '10px', 
        'active-color'     => '#7B7B88', 
        'inactive-color'   => '#D0D0D0' 
    ); 
    
    Replace line:
    $bar = new HTML_Progress(&$p, $layout); 
    
    By line:
    $bar = new HTML_Progress(&$p); 
    
    Replace also line:
    $css =& $bar->getStyle();
    
    By line:
    $css =& new HTML_CSS(); 
    
    And add after line:
    $p->addStyleSheet("./styles.css"); 
    
    a new line like this one:
    $p->addStyleSheet("./progress.css"); 
    
    Where you'll find all color and presentation declarations related to progress bar. StyleSheet progress.css could be look like:
    #progressBar {
    	background-color: white;
    	font-family: Verdana, Arial, Helvetica, sans-serif;
    	font-size: 14px;
    	border: 2px solid #7B7B88;
    	width: 200px;
    	padding: 2px;
    }
    
    #installationProgress {
    	text-align: right;
    }
    
    #progressCell0,#progressCell1,#progressCell2,#progressCell3,#progressCell4,
    #progressCell5,#progressCell6,#progressCell7,#progressCell8,#progressCell9
    {
    	float: left;
    	width: 10px;
    	height: 20px;
    	margin-right: 2px;
    }
    
    .cell0 {
    	background-color: #d0d0d0;
    }
    
    .cell1 {
    	background-color: #7B7B88;
    }
    
  5. More on subject

    Searching a javascript solution for :

The End

For questions and remarks, contact me laurent.laville@worldonline.fr.


Article URL: http://farell.free.fr/en/pear/sources/HTML_Progress/docs/index.html
Article publication: July 23, 2003
Article author: Laurent Laville

$Id: index.html,v 1.2 2003/07/31 17:30:56 Farell Exp $