ProgressClass v1.0 Manual
 (c) 2002 by Boris Wylutzki / www.edv-internet.de --- english translation by L. Schmidt

This program is freeware. You can modify or pass it on under the conditions of the GNU general Public License, published by the Free Software Foundation, either in accordance with version 2 of the license or (after your option) each later version.

The publication of this program takes place in the hope that it will be useful for you, but WITHOUT ANY GUARANTEE, even without the implicit guarantee of being ready for the market or the USABILITY FOR A CERTAIN PURPOSE. You can find details in the GNU general Public License.

You should have received a copy of the GNU general Public License together with this program. If not, write the Free software Foundation, Inc., 59 Temple Place, suite 330, Boston, MA 02111-1307, USA.

If you need a license for using the application in payable software packages, please contact the author via www.edv-internet.de.

Program-description

ProgressClass makes a PHP-Class for the dynamic display and change of a progress bar available. In a Windows-styled window, the progress can even be shown during the execution of the scripts, for example with the loading or the output of the file, sending of e-mails or processing of data bases. The progress bar can be faded out at the end of the side. Features: optional abort button; dynamic change of label, color, percent; free size and positioning.

System-requirements

The server requires PHP 4.x or higher with correctly installed browscap.ini. The Client requires IE 5.x or higher as well as Netscape 6.x or higher. Other browsers are not tested. ProgressClass tests the browser version independently and shows no progress bar on too old versions; an own browser check is not needed.

Installation

Simply copy the files ProgressClass.php and js.inc.php onto your Webspace.

Application

ProgressClass is completely object-oriented. It makes available a class for generating, editing and removal of the progress bar. If several progress bars are required, the class can be run in several instances without problems several times (also simultaneously). Basically, the progress bar works as follows:

  1. Integrate the class:
    require('ProgressClass.php');

  2. Generate oneinstance of the class:
    $progress=new ProgressClass();

  3. Select the desired options (see below). This step is optional, the class comes with default settings. Example:
    $progress->setWidth(300);
    $progress->setPosition('center',20);
    ... etc.

  4. Generate and show progress bar:
    $progress->make();

  5. Change the percentage or other attitudes:

    $progress->setPercent(10);
    ...
    $progress->setPercent(45);
    ...
    $progress->setPercent(80);
    $progress->setLabel('Clearing RAM...');
    ...
    $progress->setPercent(100);
    $progress->setLabel('Done!');


  6. Remove progress bar, so that it is no longer shown in the browser:
    $progress->hide();

Description of the functions

ProgressClass()

The function is called by instancing the class and is makes internal initializations. You may also use many progress bars (also simultaneously) through generating instancing of new classes. All progress bars have independ attitudes to each other and can be shown and changed separately.

Requires no parameters.

$progress->new ProgressClass();

setWidth($width);

Defines the width (outer edge of the window) of the progress bar in pixels. 350 pixels are default.

Calling this function after make() has no effect.

$progress->setWidth(300);

setPosition($left=NULL,$top=NULL);

Defines the position (upper left corner) of the progress bar (outer edge of the window) within the indicated documents/frames in pixels. Default is 'center','center-65'.

The first parameter marks the spacing of the upper left corner to the left margin, the second to the upper margin. You can also declare only one of these parameters, then the second one will be kept. If you would like to declare only the second parameter, the first must be NULL.

Instead of absolute numbers you also can indicate 'center'', so that the window is centered in the display. Even a combination is possible, for example'center-30'.

Calling this function after make() has no effect.

$progress->setPosition(100,30);

$progress->setPosition(NULL,30); // keep default for $left

$progress->setPosition(100); // keep default for $top

$progress->setPosition('center','center-30'); // center, shifted upside a little

setButton($label,$url,$target='_self')

Add a button to the progress bar, on click a new side is opened. The button can be marked "Abort" for example. If it is clicked, a new side will be loaded, so that the implementation of the current site is aborted (only if target=' _self' ).

The first parameter declares the label of the button, the second one the target URL. The optional third parameter is used for the link target.

Calling this function after make() has no effect.

$progress->setButton('Abort','/pages/abort.php');

$progress->setButton('Info','info.php','_blank');

setPercent($percent)

Defines the percentage of the progress bar. Default is 0.

The parameter must be a number, without a percent-mark.

This function can also be called after make() more then once in order to change the percentage dynamically (DHTML).

$progress->setPercent(25);

setPerX($some,$all)

Defines the percentage of the progress bar and converts the specified values into percent..

The first parameter represents the current position of altogether as much positions as second parameter indicates. If you read a file or a MySQL-Result, you hand over the number of the entries for $all and for $some the current position of the pointer of the file/result.

This function can also be called after make() more then once in order to change the percentage dynamically (DHTML).

$gesamt=1500;
for ($i=1;$i<=$gesamt;$i++)
  $progress->setPerX($i,$gesamt);

setLabel($label)

Defines the label of the progress bar. Default is "Please wait..."

This function can also be called after make() more then once in order to change the percentage dynamically (DHTML).

$progress->setLabel('Seite wird geladen ...');

setBarColor($color)

Defines the color of the progress bar. Default is dark-blue.

The color has to be declared in HTML-Color-Code.

This function can also be called after make() more then once in order to change the percentage dynamically (DHTML).

$progress->setBarColor('#FF0000'); // red

hide()

Make the progress bar invisible. Should be called in the end, so that the visitor can view the side without the progress bar.

Requires no parameters.

This function should only be called after make() (DHTML).

$progress->hide();

show()

Shows the progress bar and is meaningful, for example if previously make(false) was called.

Requires no parameters.

This function should only be called after make() (DHTML).

$progress->show();

make($show=true)

Creates the progress bar and passes it to the browser.

Important: The function must only be called after the <body>-Tag was sent to the browser!

You can optional declare with the parameter, whether the progress bar is also immediately shown visible or not. Default is true (=yes).

$progress->make();

$progress->make(false); // Create only , don't show yet.