17.3 HTML_Page2 
| Besprochene Version: 0.5.0 | Lizenz: PHP-Lizenz 3.0 |
| Klassendatei(en): HTML/Page2.php | |
HTML_Page ist eine Klasse, mit der Sie recht einfach (X)HTML-Seiten generieren können. Natürlich können Sie den HTML-Code auch direkt in Ihre Seiten einbetten, aber das führt oft dazu, dass so eine Seite nicht gut lesbar ist. Eine Ausgabe mit PHP kann den Code besser lesbar und somit wartbarer machen. Das Ziel dieses Pakets ist es, das Grundgerüst einer Seite auszugeben. Die eigentlichen Inhalte und Layout-Anweisungen müssen Sie von Hand oder mit anderen Paketen erstellen.
Auch wenn die hier genutzte Version 0.5.0 noch eine Beta-Version ist, so ist sie meiner Erfahrung nach durchaus stabil, da sie sich aus HTML_Page, der PHP 4-Variante dieser Klasse, ableitet, die seit einiger Zeit den Status stable hat.
Auch in diesem Fall gestaltet sich die Nutzung der Klasse erfreulich einfach.
require_once 'HTML/Page2.php';
$seite = new HTML_Page2();
$seite->addBodyContent('<h1>Hallo Welt</h1>');
$seite->display();Listing 17.2 Ausgabe einer einfachen Seite
Listing 17.2 generiert den folgenden Code:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <meta name="Generator" content="PEAR HTML_Page" /> <title>New XHTML 1.0 Transitional Compliant Page</title> </head> <body> <h1>Hallo Welt</h1> </body> </html>
Wie Sie sehen, wird eine komplette XHTML-Seite inklusive der Angabe zum Namespace und der Processing-Instructions generiert.
Die Methode addBodyContent() fügt, wie Sie sich sicher schon denken können, Inhalt für den Body der Seite hinzu, wobei es sich hierbei um ein echtes Hinzufügen handelt. Bereits enthaltener Content wird also nicht überschrieben.
Die Methode display() dient dazu, die Seite zu generieren und auszugeben.
Der Konstruktor akzeptiert allerdings noch einige Parameter, mit denen Sie die grundlegenden Einstellungen der Seite beeinflussen können. Möchten Sie nur einen Parameter beeinflussen, übergeben Sie den entsprechenden Wert als String. Wünschen Sie mehrere Veränderungen, müssen Sie die entsprechenden Werte in Form eines Arrays übergeben. Das heißt: Wenn Sie beispielsweise die Processing-Instructions und Namespace-Informationen unterdrücken wollen, übergeben Sie dem Konstruktor einfach den Parameter 'doctype="none"'. Möchten Sie allerdings die Ausgabe der Doctype-Angabe unterdrücken und die Darstellung des Zeilenumbruchs auf den Windows-Modus stellen, nutzen Sie Folgendes:
Der Konstruktor erkennt hierbei die Schlüsselwörter und Werte aus Tabelle 17.2:
Diese Eigenschaften können auch einzeln über entsprechende Methoden angesprochen werden, wobei die Werte, die diese Funktionen akzeptieren, denen aus Tabelle 17.2 entsprechen. Allerdings würde ich Ihnen empfehlen, die Werte wenn möglich über den Konstruktor zu setzen, weil die Methoden teilweise noch in anderen Paketen definiert sind und die Gefahr, dass sie umbenannt werden oder Ähnliches, somit größer ist.
17.3.1 Methoden zur Manipulation des Heads
Da das Paket dazu dient, das Grundgerüst einer HTML-Seite zu generieren, sind naturgemäß relativ viele Methoden zur Manipulation der Head-Elemente vorgesehen.
Als Erstes ist hier sicher das title-Tag zu nennen, dessen Inhalt Sie mit setTitle() festlegen können. Die Methode bekommt nur einen Parameter, nämlich den Titel der Seite, übergeben. Einen bereits gesetzten Titel können Sie mit getTitle() wieder auslesen, wenn das nötig sein sollte.
Ein wichtiger Punkt sind auch die Meta-Informationen, die im Kopf der Seite abgelegt werden können. Die meisten Meta-Daten, wie keywords oder description, können Sie einfach mit der Methode setMetaData() setzen. Sie bekommt an erster Stelle den Namen der Meta-Information und danach den eigentlichen Content übergeben. Mit
würden Sie also ein <meta name="description" content="Eine echt schöne Seite" /> einfügen. Die Methode testet hierbei nicht den Namen, den Sie nutzen. Somit können Sie also auch jederzeit auf Dublin-Core-Metas zurückgreifen oder selbst definierte nutzen. Möchten Sie nicht das name-, sondern das http-equiv-Attribut nutzen, übergeben Sie als dritten Parameter einfach ein true.
Möchten Sie allerdings den Typ des Inhalts mithilfe des http-equiv-Attributs festlegen, ist hierzu die Methode setMetaContentType() vorgesehen, die den Zeichensatz und den MIME-Type direkt aus dem Objekt bezieht. Es werden also die Werte genutzt, die Sie dem Konstruktor übergeben haben, oder die Standardwerte UTF-8 und text/html übernommen.
Die andere Meta-Information, die gesondert behandelt wird, ist die Refresh-Funktionalität, die Sie mit setMetaRefresh() einbringen können. Die Methode bekommt als ersten Parameter eine Zahl in Sekunden übergeben, nach denen die Aktualisierung ausgeführt wird. Standardmäßig lädt die Seite sich selbst erneut. Um eine andere Seite anzusprechen, können Sie eine komplette, absolute URL als zweiten Parameter übergeben. Ein Sonderfall ist, wenn die Seite sich selbst aufrufen soll und der zweite Aufruf nicht über das http-, sondern das https-Protokoll erfolgen soll bzw. umgekehrt. In einem solchen Fall übergeben Sie als zweiten Parameter den String 'self' und als dritten ein true, wenn das https-Protokoll genutzt werden soll. Andernfalls bindet die Methode die http-Variante ein.
Um mehrere HTML-Dateien mit einem Objekt generieren zu können, benötigen Sie unter Umständen noch die Methode unsetMetaData(). Sie entfernt die Meta-Information, deren Name ihr übergeben wurde. Sollte es sich um ein http-equiv-Meta-Tag handeln, benötigt sie als zweiten Parameter noch den booleschen Wert true.
In diesem Zusammenhang sollte nicht unerwähnt bleiben, dass das Paket standardmäßig das folgende Meta-Tag einfügt:
<meta name="Generator" content="PEAR HTML_Page" />
Dieses Tag können Sie mit einem Aufruf von $seite->unsetMetaData('Generator'); entfernen.
Das FavIcon, ein kleines Icon, das z. B. in der Adressleiste des Browsers oder in den Bookmarks auftauchen kann, können Sie auch einbinden. addFavicon(), die Methode, die das Icon für Sie einbindet, bekommt standardmäßig die absolute URI des Icons übergeben. Als weitere Parameter können Sie noch den MIME-Type des Icons, normalerweise image/x-icon, sowie den Verwendungszweck des Icons angeben. Als Verwendung können Sie shortcut, icon oder beides, getrennt durch ein Leerzeichen, angeben. shortcut soll bewirken, dass das Icon nur für die Bookmarks genutzt wird, wohingegen icon eine Nutzung in der Adresszeile definiert. Da insbesondere der Internet Explorer diese Unterscheidung nicht unterstützt, ist es allerdings eher fragwürdig, den Verwendungstyp anzugeben. Aufgrund der unterschiedlichen Verwendungszwecke ist es möglich, diese Methode mehrfach aufzurufen.
Da die meisten Seiten nicht nur aus reinem (X)HTML bestehen, ist es natürlich auch möglich, CSS und JavaScript einzubinden. In beiden Fällen können Sie den Code direkt in die Seite einbetten oder auf eine externe Datei verweisen.
Um ein Cascading-Stylesheet direkt in die Datei einzubinden, nutzen Sie addStyleDeclaration(). Die Methode akzeptiert CSS-Code, der direkt in einer Variable übergeben wird, oder – was sehr praktisch ist – ein Objekt, das eine toString()- oder toHtml()-Methode kennt. Das ist deswegen sehr praktisch, weil PEAR::HTML_CSS-Objekte die Methode unterstützen. Übergeben Sie ein Objekt, das keine dieser Methoden unterstützt, wird ein PEAR_Error-Objekt zurückgeliefert.
addStyleDeclaration() akzeptiert als zweiten Parameter den Typ des eingebundenen Stylesheets. Da es sich standardmäßig um CSS handelt, ist die Vorbelegung 'text/css'.
Um auf eine externe CSS-Datei zu verweisen, steht addStyleSheet() zur Verfügung. Dieser Methode muss mindestens die URL der Stylesheet-Datei übergeben werden. Des Weiteren können Sie Ihr als zweiten Parameter auch einen Content-Type und als dritten Parameter einen Medien-Typ übergeben, für den dieses Stylesheet gedacht ist.
Eine ähnliche Vorgehensweise ist für das Einbinden von JavaScript vorgesehen. Um JavaScript direkt in die HTML-Seite einzubinden, können Sie addScriptDeclaration() nutzen. Auch hierbei gilt, dass die Methode entweder eine Variable mit dem Script oder ein Objekt erwartet, das eine toString()- bzw. toHtml()-Methode unterstützt. Übergeben Sie ein Objekt, das die Methode nicht kennt, wird ein PEAR_Error generiert. Mit einem zweiten Parameter können Sie auch hier den Typ des Inhalts festlegen. Da die meisten Internet-Anwendungen JavaScript als clientseitige Scriptsprache nutzen, ist dieses auch als Default-Wert eingestellt. Die Einbindung einer externen JavaScript-Datei erfolgt über addScript(). Der erste Parameter ist, ähnlich wie beim Stylesheet-Pendant, die URI der einzubindenden Datei. Mit dem zweiten Parameter, der optional ist, kann auch hier definiert werden, ob es sich um JavaScript oder eine andere Script-Sprache handelt.
17.3.2 Methoden zur Manipulation des Bodys
Zum Generieren des Bodys sind – wie schon erwähnt – nicht so viele Methoden vorgesehen. Bevor ich auf den Inhalt des Bodys zu sprechen komme, stellt sich die Frage, wie das Body-Tag selbst um Attribute ergänzt werden kann. Dies ist dann sehr hilfreich, wenn Sie beispielsweise einen Event-Handler integrieren oder eine Hintergrundfarbe setzen wollen. Die Attribute können hierbei in Form eines Arrays oder eines Strings übergeben werden. Das heißt, der Aufruf
Das Hinzufügen von Inhalten geschieht mit der Methode addBodyContent(). Ihr wird einfach der Inhalt übergeben, der in den Body eingefügt werden soll. Die Daten werden dabei immer an die bereits vorhandenen angehängt. Auch hierbei können Sie wieder ein Objekt übergeben, das über eine toString()- oder toHtml()-Methode verfügt, wie z. B. eines der Klasse HTML_Table.
Um einen bestehenden Body zu löschen, ist unsetBody() vorgesehen.
Liegt der gesamte Body schon in einer Variable oder einem Objekt vor, können Sie auch setBody() nutzen. Diese Methode überschreibt die bestehenden Daten mit den neuen, die ihr übergeben wurden.
17.3.3 Ausgabe der HTML-Daten
Neben der schon erwähnten Methode display(), mit der Sie die fertige Seite an den Client senden können, haben Sie auch die Möglichkeit, die Daten in einer Datei abzuspeichern. Die hierfür zuständige Methode toFile() bekommt den Namen und Pfad übergeben, unter dem die Daten abgelegt werden sollen. Kann die Zieldatei nicht erzeugt werden, liefert diese Methode ein PEAR_Error-Objekt zurück.
Die dritte Möglichkeit besteht darin, die generierten Daten als String zurückzuliefern, wofür toHtml() vorgesehen ist.
Hier noch ein etwas komplexeres Beispiel:
require_once 'HTML/Page2.php'; // Definieren der Vorgaben fuer die Seite $options = array ( 'lineend' => 'win', 'tab' => ' ', 'charset' => 'iso-8859–1', 'doctype' => 'none' ); $seite = new HTML_Page2($options); // Titel festlegen $seite->setTitle('Ein kleiner Test'); // Ein kleines JavaScript einbinden $seite->addScriptDeclaration('window.alert("Hallo :-)")'); //Schriftart fuer den Body einbinden $seite->addStyleDeclaration("body{\n\tfont-family:arial;\n}"); // Eine kleine Beschreibung in den Meta-Informationen $seite->setMetaData('description', 'Eine Seite zum Testen'); // Standard-Meta-Tag entfernen $seite->unsetMetaData('Generator'); // Attribute fuer das Body-Tag setzen $seite->setBodyAttributes ('text="white" bgcolor="black"'); // Content fuer die Seite einfuegen $seite->setBody('Dies ist eine Text-Seite'); $seite->addBodyContent('<br />Hier kommt die zweite Zeile'); //Datei speichern $erg=$seite->toFile('datei.html');_$ret_if (PEAR::isError($erg)) { die ($erg->getMessage()); }
Listing 17.3 Generieren einer kompletten Seite mit HTML_Page2
Listing 17.3 generiert den folgenden HTML-Code:
<html> <head> <meta name="description" content="Eine Seite zum Testen" /> <title>Ein kleiner Test</title> <style type="text/css"> <!-- body { font-family:arial; } --> </style> <script type="text/javascript"> // <!-- window.alert("Hallo :-)") // --> </script> </head> <body text="white" bgcolor="black"> Dies ist eine Text-Seite <br />Hier kommt die zweite Zeile </body> </html>
