ProgressClass v1.0 Anleitung
(c) 2002 Boris Wylutzki / www.edv-internet.de

Dieses Programm ist freie Software. Sie können es unter den Bedingungen der GNU General Public License, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder modifizieren, entweder gemäß Version 2 der Lizenz oder (nach Ihrer Option) jeder späteren Version.
Die Veröffentlichung dieses Programms erfolgt in der Hoffnung, daß es Ihnen von Nutzen sein wird, aber OHNE IRGENDEINE GARANTIE, sogar ohne die implizite Garantie der MARKTREIFE oder der VERWENDBARKEIT FÜR EINEN BESTIMMTEN ZWECK. Details finden Sie in der GNU General Public License.
Sie sollten eine Kopie der GNU General Public License zusammen mit diesem Programm erhalten haben. Falls nicht, schreiben Sie an die Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
Falls Sie eine Lizenz für die Verwendung in kostenpflichtigen Softwarepaketen benötigen, kontaktieren Sie bitte den Autor unter www.edv-internet.de.

Programmbeschreibung

ProgressClass stellt eine PHP-Klasse für die dynamische Anzeige und Veränderung eines Fortschrittsbalkens zur Verfügung. In einem Fenster im Windows-Stil kann noch während der Laufzeit des Scripts der Fortschritt angezeigt werden, z.B. beim Laden/Ausgeben der Seite, Versenden von E-Mails oder Bearbeiten von Datenbanken. Am Ende der Seite kann der Fortschrittsbalken wieder ausgeblendet werden. Features: optionaler Abbrechen-Button; dynamische Änderung von Beschriftung, Farbe, Prozent; freie Größe und Positionierung.

Systemvoraussetzungen

Der Server benötigt PHP 4.x oder höher incl. korrekt installierter aktueller browscap.ini. Der Client benötigt den IE 5.x oder höher bzw. Netscape 6.x oder höher. Andere Browser-Hersteller sind nicht getestet. ProgressClass prüft selbständig die Browserversion und zeigt bei zu alter Version keinen Fortschrittsbalken an; eine eigene Browserüberprüfung brauchen Sie nicht zu verwenden.

Installation

Kopieren Sie einfach die Dateien ProgressClass.php und js.inc.php auf ihren Webspace.

Anwendung

ProgressClass ist komplett objektorientiert. Es stellt eine Klasse zum Erzeugen, Bearbeiten und Löschen des Fortschrittsbalkens zur Verfügung. Wenn mehrere Fortschrittsbalken benötigt werden, kann die Klasse auch ohne Probleme mehrmals instanziert werden (auch gleichzeitig). Grundsätzlich stellt sich der Einsatz folgendermaßen dar:

1. Einbinden der Klasse:

   require('ProgressClass.php');

2. Erzeugen einer Instanz der Klasse:

   $progress=new ProgressClass();

3. Einstellen der gewünschten Optionen (siehe unten). Dieser Schritt ist optional, die Klasse ist mit Standardeinstellungen vorbelegt. Beispiel:

   $progress->setWidth(300); $progress->setPosition('center',20); ... usw.

4. Fortschrittsbalken generieren und ausgeben:

   $progress->make();

5. Ändern der Prozentanzeige oder anderer Einstellungen:

   $progress->setPercent(10); ... $progress->setPercent(45); ... $progress->setPercent(80); $progress->setLabel('Speicher wird aufgeräumt ...'); ... $progress->setPercent(100); $progress->setLabel('Fertig!');

6. Fortschrittsbalken löschen, so daß er nicht mehr im Browser angezeigt wird:

   $progress->hide();

Beschreibung der Funktionen

ProgressClass()

> Die Funktion wird durch Instanzieren der Klasse aufgerufen und nimmt interne Initialisierungen vor. Sie können beliebig viele Fortschrittsbalken (auch gleichzeitig) durch Instanzieren neuer Klassen erzeugen. Alle Fortschrittsbalken haben voneinander unabhänge Einstellungen und können getrennt angezeigt und geändert werden.

> Benötigt keine Parameter.

> $progress->new ProgressClass();

setWidth($width);

> Definiert die Breite des Fortschrittbalkens (äußerer Rand des Fensters) in Pixeln. Standardeinstellung sind 350 Pixel.

> Der Aufruf dieser Funktion nach make() hat keine Wirkung.

> $progress->setWidth(300);

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

> Definiert die Position (obere linke Ecke) des Fortschrittsbalkens (äußerer Rand des Fensters) innerhalb des angezeigten Dokuments/Frames in Pixeln. Standardeinstellung ist 'center','center-65'.

> Der erste Parameter bezeichnet den Abstand der oberen linken Ecke zum linken Seitenrand, der zweite zum oberen Seitenrand. Sie können auch nur einen der Parameter angeben, der zweite behält dann die Standardeinstellung. Wenn Sie nur den zweiten Parameter angeben möchten, muß der erste NULL sein.

> Anstelle von absoluten Zahlen können Sie auch 'center' angeben, so daß das Fenster zentriert im Anzeigebereich angezeigt wird. Möglich ist sogar eine Kombination z.B. 'center-30'.

> Der Aufruf dieser Funktion nach make() hat keine Wirkung.

> $progress->setPosition(100,30);

> $progress->setPosition(NULL,30); // Standardeinstellung für $left beibehalten

> $progress->setPosition(100); // Standardeinstellung für $top beibehalten

> $progress->setPosition('center','center-30'); // Zentriert, etwas nach oben verschoben

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

> Fügt dem Fortschrittsbalken einen Button hinzu, auf dessen Klick eine neue Seite geöffnet wird. Der Button kann z.B. mit "Abbrechen" beschriftet werden. Wenn er angeklickt wird, wird eine neue Seite geladen, so daß die Ausführung der aktuellen Seite abgebrochen wird (nur wenn target='_self').

> Mit dem ersten Parameter wird die Beschriftung des Buttons, mit dem zweiten die Ziel-URL angegeben. Der optionale dritte Parameter bezeichnet das für den Link verwendete Target.

> Der Aufruf dieser Funktion nach make() hat keine Wirkung.

> $progress->setButton('Abbrechen','/seiten/abbruch.php');

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

setPercent($percent)

> Definiert die Prozentanzeige des Fortschrittsbalkens. Standardeinstellung ist 0.

> Der Parameter muß als Zahl, ohne Prozentzeichen angegeben werden.

> Diese Funktion kann auch nach make() noch öfter aufgerufen werden, um die Prozentanzeige dynamisch zu ändern (DHTML).

> $progress->setPercent(25);

setPerX($some,$all)

> Definiert die Prozentanzeige des Fortschrittsbalkens und rechnet dafür die angegebenen Werte in Prozent um.

> Der erste Parameter stellt die aktuelle Position von insgesamt soviel Positionen, wie der zweite Parameter bezeichnet, dar. Wenn Sie eine Datei oder ein MySQL-Result einlesen, übergeben Sie für $all die Anzahl der Einträge und für $some die aktuelle Position des Dateizeigers/Result-Zeigers.

> Diese Funktion kann auch nach make() noch öfter aufgerufen werden, um die Prozentanzeige dynamisch zu ändern (DHTML).

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

setLabel($label)

> Definiert die Beschriftung des Fortschrittsbalkens. Standardeinstellung ist "Bitte warten ..."

> Diese Funktion kann auch nach make() noch öfter aufgerufen werden, um das Label dynamisch zu ändern (DHTML).

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

setBarColor($color)

> Definiert die Farbe des Fortschrittsbalkens. Standardeinstellung ist dunkelblau.

> Die Farbe muß als HTML-Color-Code angegeben werden.

> Diese Funktion kann auch nach make() noch öfter aufgerufen werden, um die Farbe dynamisch zu ändern (DHTML).

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

hide()

> Macht den Fortschrittsbalken unsichtbar. Sollte am Ende der Ausgabe aufgerufen werden, damit der Besucher die Seite ohne den Fortschrittsbalken betrachten kann.

> Benötigt keine Parameter.

> Diese Funktion sollte nur nach make() aufgerufen werden (DHTML).

> $progress->hide();

show()

> Macht den Fortschrittsbalken sichtbar und ist z.B. sinnvoll, wenn vorher make(false) aufgerufen wurde.

> Benötigt keine Parameter.

> Diese Funktion sollte nur nach make() aufgerufen werden (DHTML).

> $progress->show();

make($show=true)

> Erstellt den Fortschrittsbalken und gibt ihn an den Browser aus.

> Wichtig: Die Funktion darf erst aufgerufen werden, nachdem der <body>-Tag an den Browser gesendet wurde!

> Optional kann durch den Parameter angegeben werden, ob der Fortschrittsbalken auch gleich sichtbar angezeigt wird. Standardeinstellung ist true (= Ja).

> $progress->make();

> $progress->make(false); // Nur ausgeben, noch nicht anzeigen.