17.13 HTML_Progress 
| Besprochene Version: 1.2.0 | Lizenz: PHP-Lizenz 3.0 |
| Klassendatei(en): HTML/Progress.php | |
Ein unschönes Problem bei Web-Applikationen ist folgende Situation: Der Server hat eine umfangreiche Aufgabe zu erfüllen, und der User, der vor dem Client sitzt, muss warten. Da er nicht weiß, was oder ob überhaupt etwas auf dem Server passiert, kann er schnell ungeduldig werden, was dann dazu führen kann, dass er den Browser schließt oder versucht, die Seite neu zu laden.
HTML_Progress stellt Möglichkeiten zur Verfügung, um einen animierten Fortschrittsbalken auf dem Bildschirm ausgeben zu lassen. Ein solcher Balken kann in einem einfachen Fall eine zeitgesteuerte Animation sein, damit der Benutzer den Eindruck hat, dass etwas passiert. Sie können den Balken aber auch in Abhängigkeit vom Fortschritt des Prozesses auf dem Server »fernsteuern«.
In einem sehr einfachen Fall könnte die Nutzung aussehen wie in Listing 17.27.
<?php
require_once ('HTML/Progress.php');
$bar = new HTML_Progress();
// Geschwindigkeit in Millisekunden
$bar->setAnimSpeed(50);
?>
<html>
<head>
<title>Progress 1</title>
<style type="text/css">
<!--
<?php
// Style-Sheet einbinden
echo $bar->getStyle();
?>
// -->
</style>
<script type="text/javascript">
<!--
<?php
// JavaScript-Code ausgeben
echo $bar->getScript();
?>
//-->
</script>
</head>
<body>
<table>
<tr>
<td style="text-align:center; font-family:arial">
Bitte warten Sie, bis der <br />
Vorgang beendet ist!</td>
</tr>
<tr><td>
<?php
// Daten fuer den Balken generieren
echo $bar->toHtml();
// Animation an den Client senden
$bar->run();
?>
</td>
</tr></table>
</body>
</html>Listing 17.27 Ausgabe eines Fortschrittsbalkens mit HTML_Progress
Wie Sie an der Verquickung von HTML und PHP schon sehen können, basiert das Paket nicht nur auf PHP. Vielmehr generiert PHP nur die JavaScript- und DHTML-Daten, die dann beim Client für die korrekte Darstellung sorgen, die Sie in Abbildung 17.14 sehen können.
Abbildung 17.14 Fortschrittsbalken
Im Kopf der Datei wird zuerst ein neues Objekt instanziiert, das dann für die Ausgabe des Balkens zuständig ist. Die Methode setAnimSpeed() legt fest, wie viel Zeit von einem Prozent bis zum nächsten verstreichen soll. Die Zeit ist hierbei in Millisekunden anzugeben, so dass der Balken in diesem Beispiel 5 Sekunden benötigt, um von 0 % auf 100 % zu laufen.
Im Kopf der HTML-Seite werden die benötigten CSS-Styles durch die Methode getStyle() eingefügt. Diese Funktionalität benötigt das PEAR-Paket HTML_CSS. Bitte vergessen Sie hierbei nicht, die notwendigen HTML-Tags einzufügen.
Ähnliches gilt für den JavaScript-Code, der benötigt wird. Dieser wird durch die Methode getScript() im Kopf der HTML-Datei ausgegeben und benötigt die entsprechenden HTML-Tags. Allerdings wird hierbei nicht auf HTML_JavaScript zurückgegriffen.
Das eigentliche Erzeugen des Balkens wird durch die letzten beiden Zeilen gewährleistet. Die Methode toHtml() erzeugt die einzelnen Animationsschritte des eigentlichen Balkens, gibt sie aber noch nicht aus. run() sendet die einzelnen Prozentangaben an den Browser und bindet die Animation des Balkens ein. Die Methode run() sendet für jede Prozentzahl Daten zum Browser. Das bedeutet also, dass der Rest der Datei erst dann zum Client geschickt wird, wenn der Balken die 100 % erreicht und die PHP-Verarbeitung somit abgeschlossen ist. Das können Sie sehr schön nutzen, indem Sie den Client danach beispielsweise mit
<script type="language/JavaScript"> self.location.href="neue_seite.php"; </script>
auf eine Folgeseite weiterleiten. Somit entsteht die Illusion, dass der Client wirklich dann weitergeleitet wird, wenn die gesamte serverseitige Arbeit abgeschlossen ist.
Das Aussehen des Balkens können Sie natürlich beeinflussen. Das HTML_Progress-Objekt stellt dazu einige Methoden zur Verfügung. Hierbei können Sie als Erstes festlegen, worauf sich die 100 % bei der Ausgabe beziehen sollen. Üblicherweise geht das System davon aus, dass 100 % auch 100 Einheiten entsprechen. Übergeben Sie der Methode setMaximum() die Zahl 10, läuft die Animation zehnmal so schnell, da die 100 % nur noch 10 Einheiten entsprechen. Mit setMinimum() können Sie definieren, wie viele Einheiten schon als »erledigt« angesehen werden. Übergeben Sie setMinimum() bei einem Maximum von 100 die Zahl 20, sind die ersten 20 % bereits als fertig markiert, wenn die Animation startet. Zusätzlich können Sie mit setIncremet() noch die Schrittweite definieren, in der der Balken inkrementiert werden soll.
Möchten Sie weitergehende Änderungen vornehmen, z. B. die Farbe verändern, benötigen Sie Zugriff auf ein Userinterface-Objekt. Eine Referenz darauf können Sie mit getUI() aus dem HTML_Progress-Objekt auslesen.
Mit diesem Objekt können Sie das Aussehen des Balkens deutlich verändern. So haben Sie mit setCellCount() die Möglichkeit, die Anzahl der Elemente festzulegen, aus denen der Balken besteht. Der Standard ist, dass ein Balken aus 10 Elementen besteht. Die Methode setOrientation() akzeptiert eine der Konstanten HTML_PROGRESS_BAR_HORIZONTAL oder HTML_PROGRESS_BAR_VERTICAL. Die erste entspricht dem Standard, und die zweite definiert, dass der Balken vertikal, also hochkant ausgegeben wird.
Mit setFillWay() können Sie über die Konstanten 'natural' oder 'reverse' steuern, wie der Balken gefüllt werden soll. Der erste String sorgt dafür, dass von links nach rechts bzw. von unten nach oben gefüllt wird. Die zweite Variante kehrt dieses Verhalten um.
Die Farben des Balkens können Sie mit setProgressAttributes() bestimmen. Diese Methode bekommt ein Array übergeben, wie im folgenden Beispiel:
$bar_ui->setCellAttributes(array( 'active-color' => '#FF0000', 'inactive-color' => '#00FF00', 'width' => 20, 'spacing' => 3 ));
Der Schlüssel 'inactive-color' definiert die Farbe, die ein Balkenelement hat, wenn es noch nicht gefüllt ist, also quasi die »Hintergrundfarbe« des Balkens. 'active-color' hingegen legt fest, mit welcher Farbe der Balken gefüllt werden soll. Die Breite eines Balken-Elements wird dem Schlüssel 'width' in Pixeln übergeben. Der Abstand der Elemente wird über den Schlüssel 'spacing' definiert. Setzen Sie ihn auf 0, grenzen die Elemente direkt aneinander.
Das Erscheinungsbild der Textausgabe (Prozentzahlen) kann über die Methode setStringAttributes() definiert werden. Auch sie erwartet ein Array mit Daten, wobei die folgenden Schlüssel unterstützt werden. Die Farbe des Textes kann über 'color' festgelegt werden. Um die Hintergrundfarbe zu manipulieren, ist der Schlüssel 'background-color' vorgesehen. Um die Größe der Schrift zu verändern, legen Sie die gewünschte Größe als Pixel-Angabe einfach im Element 'font-size' ab.
Die Breite des Bereichs, in dem die Schrift ausgegeben wird, können Sie auch ändern. Dieser Bereich ist mindestens so breit wie der Fortschrittsbalken. Wenn Sie mit dem Schlüssel 'width' eine Zahl übergeben, die mehr Pixel beschreibt, als der Balken breit ist, wird der Textbereich auf diese Breite festgelegt. Bei einer vertikalen Darstellung wird hiermit auch die Breite beeinflusst.
Mit den Schlüsseln 'align' und 'valign' können Sie die Position des Textes definieren. 'align' legt hierbei die Position innerhalb des Textbereichs fest und akzeptiert die Werte 'left' und 'right'. Mit 'valign' können Sie festlegen, ob der Textbereich sich links ('left'), rechts ('right'), über ('top') oder unter ('bottom') dem Balken befindet.
Üblicherweise wird kein Rahmen um den Fortschrittsbalken gelegt. Allerdings können Sie das mit der Methode setBorderAttributes() machen, wenn Sie wollen. Auch sie bekommt ein Array übergeben. Der Schlüssel 'width' definiert hierbei die Breite des Rahmens in Pixeln. Neben der Farbe des Rahmens, die mit 'color' festgelegt wird, können Sie sich für ein Erscheinungsbild entscheiden, das an den Schlüssel 'style' übergeben wird. Hier sind die für CSS zulässigen Linienformatierungen wie 'dotted', 'dashed', 'solid', 'double', 'groove', 'ridge', 'inset' und 'outset' zulässig.
Wenn Sie das Beispiel aus Listing 17.27 um diese Zeilen ergänzen:
// Referenz auf UI-Objekt holen $bar_ui=$bar->getui(); // Ausrichtung veraendern $bar_ui->setOrientation(HTML_PROGRESS_BAR_VERTICAL); // Balken veraendern $bar_ui->setCellAttributes(array( 'active-color' => '#AAAAAA', 'inactive-color' => '#000000', 'width' => 30, 'spacing' => 0)); // Text manipulieren $bar_ui->setStringAttributes(array( 'background-color' => '#000000', 'color' => 'white', 'align'=>'left', 'valign'=>'right', 'width'=>100, 'font-size' => 30)); // Rahmen definieren $bar_ui->setBorderAttributes(array( 'width'=>5, 'style'=>'dotted'));
ergibt sich ein Balken wie in Abbildung 17.15.
Abbildung 17.15 Veränderter Fortschrittsbalken
Nun gibt es aber in einigen Fällen die Situation, dass Sie nicht genau vorhersagen können, wie viel Zeit ein bestimmter Prozess benötigt. Somit ist es auch schwierig, eine Aussage darüber zu machen, wie lange der Fortschrittsbalken laufen soll. In so einem Fall können Sie recht elegant mit dem »Indeterminate Mode« arbeiten. In diesem Modus wird der Balken nicht nach und nach gefüllt, sondern ein gefülltes Element läuft immer wieder von einer Seite zur anderen durch den Balken. Somit weiß der Benutzer, dass noch etwas passiert.
Ein einfaches Beispiel zur Nutzung des Indeterminate Mode finden Sie in Listing 17.28.
<?php
require_once ('HTML/Progress.php');
// Der Handler, der unsere Arbeit macht
function handler($progress_value, $bar)
{
// Die Variable counter wird zur Ablaufsteuerung genutzt
static $counter;
if (false===isset($counter))
{
$counter=1;
}
$counter++;
// Hier passieren schrecklich komplizierte Sachen
// Animationswartezeit verschlafen
$bar->sleep();
// Ende unserer Arbeit erreicht?
if (50 === $counter)
{
// Indeterminate Mode aus
$bar->setIndeterminate(false);
// Wieder von vorne anfangen
$bar->setValue(0);
// Groessere Schrittweite
$bar->setIncrement(25);
// Text zuruecksetzen
$bar->setString(null);
}
}
$bar = new HTML_Progress();
$bar->setAnimSpeed(150);
// Platz fuer Textausgabe reservieren
$bar->setStringPainted(true);
//String ueberschreiben
$bar->setString('');
// Indeterminate einschalten
$bar->setIndeterminate(true);
// Handler definieren
$bar->setProgressHandler('handler');
?>
<html><head><title></title>
<style type="text/css">
<!--
<?php echo $bar->getStyle(); ?>
// -->
</style>
<script type="text/javascript">
<!--
<?php echo $bar->getScript(); ?>
//-->
</script>
</head>
<body>
<?php
echo $bar->toHtml();
$bar->run();
?>
</body></html>Listing 17.28 Nutzung des Indeterminate Mode
Ich möchte Ihren Blick erst auf das eigentliche Hauptprogramm richten, bevor ich zu der Funktion komme.
Im Hauptprogramm wird erst sichergestellt, dass Platz für die Ausgabe der Prozentzahl vorhanden ist. Zwar wird die im Indeterminate Mode normalerweise nicht ausgegeben, weil sie immer wieder von 0 bis 100 läuft, aber später, zum Abschluss des Codes lasse ich sie wieder ausgeben. Die Methode setStringPainted() bekommt dazu ein true übergeben. Zusätzlich muss mit der Methode setString() aber noch ein Leerstring an das System übergeben werden, der verhindert, dass eine Ausgabe erfolgt. Danach kann der Indeterminate Mode mit setIndeterminate(true) eingeschaltet werden.
In der nächsten Zeile folgt dann noch ein entscheidender Schritt. Hier wird eine Callback-Funktion mithilfe von setProgressHandler() beim System angemeldet. Diese Funktion, die in diesem Beispiel handler() heißt, ist am Anfang des Listings definiert und muss zwei Parameter akzeptieren. Der erste ist die aktuelle Prozentzahl, die die Anwendung gerade durchläuft. Der zweite Parameter ist eine Referenz auf das HTML_Progress-Objekt.
Die statische Variable $counter, die Sie in der Funktion finden, dient lediglich dazu, eine Abbruchbedingung definieren zu können.
Die Methode sleep(), die mithilfe der übergebenen Referenz aufgerufen wird, dient dazu, die Wartezeit, die mit setAnimSpeed() gesetzt wurde, ablaufen zu lassen. Wird die Methode nicht aufgerufen, »rennt« die Animation einfach durch.
Die nachfolgende if-Abfrage prüft, ob das Ende der Arbeit erreicht ist. In diesem Fall ist das Ende der fiktiven Arbeit also erreicht, wenn die Variable $counter den Wert 50 enthält. Ist das der Fall, wird der Indeterminate Mode ausgeschaltet. Mithilfe von setValue(0) wird die Animation wieder auf die Ausgangsstellung gesetzt. Da ja schon alle Schritte erledigt sind und ich den Anwender nicht unnötig warten lassen möchte, habe ich die Schrittweite mit setIncrement(25) auf 25 % gesetzt, so dass nur noch vier Animationsschritte folgen. Durch setString(null) wird der Ausgabestring auf seinen Default-Wert zurückgesetzt, was dazu führt, dass die Prozentzahlen wieder ausgegeben werden.
Allerdings wäre es nicht unbedingt nötig, den Modus wieder zu ändern. Sie können aus der Callback-Funktion heraus jederzeit Daten mit echo oder print ausgeben. Somit können Sie den Benutzer auch hier wieder mit ein wenig JavaScript direkt weiterleiten.
Das sind nur einige der Möglichkeiten, die HTML_Progress bietet. Reichen Ihnen die hier vorgestellten Fortschrittsbalken nicht aus, möchte ich Sie auf die externe Homepage des Pakets verweisen, die Sie unter http://pear.laurent laville.org/HTML_Progress/ finden. Dort sind insbesondere noch viele Beispiele für verschiedene Formatierungen zu finden.
