11.3 Text_Wiki 
| Besprochene Version: 1.0.0RC1 | Lizenz: LGPL |
| Klassendatei(en): Text/Wiki.php | |
Das Paket Text_Wiki kann Texte, die in der Wiki-Syntax vorliegen, schnell und einfach in andere Formate wie XHTML konvertieren. Natürlich stellt sich zum Ersten die Frage, was ein Wiki ist. Ein Wiki ist üblicherweise eine Ansammlung von Seiten, die von mehreren Personen gleichberechtigt gepflegt werden. Wikis, deren Name übrigens aus dem Hawaiianischen kommt und »schnell« bedeutet, werden oft für Wissenssammlungen wie beispielsweise die Wikipedia (www.wikipedia.de) eingesetzt.
Das Paket stellt keine Funktionen zum Verwalten oder Speichern der Texte bereit. Es beinhaltet nur eine Konvertierung der Texte von der Wiki-Syntax in ein anderes Format. Momentan werden nur XHTML, das LaTeX-Format und einfacher Text als Ausgabeformate unterstützt. Renderer für weitere Ausgabeformate sind allerdings in Vorbereitung. Nachfolgend werde ich mich primär auf die Konvertierung nach XHTML konzentrieren, da es sicher die üblichste Ausgabe für ein Wiki ist.
Im Endeffekt ist die Vorgehensweise recht einfach. Sie formatieren den Text mit den entsprechenden Wiki-Platzhaltern und übergeben ihn dann an das Text_Wiki-Objekt. Diesem teilen Sie mit, welches Ausgabeformat Sie wünschen, und schon kann der Text gerendert werden. Unter Umständen benötigt das Paket noch einige weitere Informationen, aber grundsätzlich war’s das auch schon.
Dabei stellt sich natürlich die Frage, mit welchen Zeichen der eingegebene Text formatiert werden kann. Zeilenumbrüche, die Sie über die Tastatur eingegeben haben, werden direkt übernommen. Der Rest der Markup-Sprache wirkt anfangs ein wenig ungewöhnlich, aber Sie werden sich recht schnell daran gewöhnen. Um einen Text z. B. kursiv darzustellen, setzen Sie ihn in doppelte Slashes, also z. B. so: //Hallo//. Einen fetten Schriftschnitt erzielen Sie mit zwei Sternen vor und hinter dem Text: **Welt**. Möchten Sie die beiden Ausgabeformate miteinander kombinieren, ist es auch möglich, sie ineinander zu verschachteln, wie Sie es aus HTML kennen. //**Hallo Welt**// wird also kursiv und fett dargestellt. In Tabelle 11.2 finden Sie eine Liste mit Markup-Befehlen.
Nachdem Sie nun einen Großteil der Wiki-Syntax kennen, folgt ein kleines Beispiel zum Konvertieren nach XHTML. Folgender Wiki-Code soll nach XHTML konvertiert werden:
+ Ein kleines Beispiel * Wiki ist # schnell # einfach **Bilder** einzubinden geht @@+++ schnell und einfach @@: http://pear.php.net/gifs/pearsmall.gif ||Eine Tabelle || kann || || auch || schnell || ||||gebaut werden, ohne HTML zu beherrschen ||
Listing 11.3 Text, der konvertiert werden soll
Der Code zum Umwandeln der Daten ist auch sehr einfach aufgebaut, wie Sie in Listing 11.4 sehen können.
<html> <head><title></title></head> <body> <?php // Klassendatei laden require_once 'Text/Wiki.php'; // Einlesen des Textes $text=file_get_contents('text.txt'); // Neues Objekt instanziieren $wiki = new Text_Wiki(); // Text nach XHTML formatieren $xhtml = $wiki->transform($text, 'Xhtml'); // Code ausgeben echo $xhtml; ?> </body> </html>
Listing 11.4 Code zum Konvertieren nach XHTML
Wie Sie sehen, benötigt der Konstruktor keine Informationen. Die Methode transform(), die die eigentliche Konvertierung vornimmt, bekommt als ersten Parameter den Text übergeben, der konvertiert werden soll, und als zweiten das Ziel, in das konvertiert werden soll. Neben Xhtml können Sie zurzeit auch Latex oder Plain angeben. Andere Formate wie PDF, Docbook oder RTF sind in Vorbereitung.
Abbildung 11.2 Ausgabe des gerenderten Texts im Browser
Mit dieser Vorgehensweise können Sie zwar schon einiges bewirken, aber ein paar Fragen sind noch offen. Zum Ersten stellt sich die Frage, wie Sie die Texte formatieren können, so dass nicht nur die Standard-HTML-Formatierung genutzt wird. Hierzu können Sie mit CSS arbeiten. Und zwar ist es möglich, den einzelnen Tags CSS-Klassen zuzuweisen, die dann von Ihnen frei definiert werden können. Leider hört sich das etwas einfacher an, als es ist.
Innerhalb einer Formatierungsvorschrift (format), also in diesem Fall XHTML, gibt es verschiedene Regeln (rules), in denen bestimmte Tags zusammengefasst sind. So umfasst die Rule Table alle Tags, die für die Erstellung einer Tabelle benötigt werden (<table>, <tr>, <td>, <th>). Für jedes dieser Tags ist dann ein config_key vorgesehen, mit dessen Hilfe der Name einer CSS-Klasse zugewiesen werden kann. Für das Tag <table> ist das z. B. der Schlüssel css_table, für das Tag <td> der Schlüssel css_td etc.
Um eine solche Klasse zuzuweisen, steht die Methode setRenderConf() zur Verfügung, die alle diese Werte in der genannten Reihenfolge übergeben bekommt.
Mit diesem Aufruf würde für den Renderer Xhtml die Rule Table so verändert, dass jedem <td> das Attribut class="tab" hinzugefügt wird. Die eigentliche Definition der Styles muss dann an anderer Stelle erfolgen. Ein wenig einfacher gestaltet sich die Vorgehensweise bei Rules, die nur ein Tag enthalten, wie z. B. <i>. In einem solchen Fall ist der Schlüssel immer css.
Nun stellt sich nur noch die Frage, welche Rules es gibt und welche Schlüssel dort enthalten sind. Hierzu möchte ich Sie auf die externe Homepage des Pakets verweisen, da diese Darstellung hier einfach zu umfangreich wäre. Die externe Homepage finden Sie unter http://wiki.ciaweb.net/yawiki/index. php?area=Text_Wiki, wobei die Informationen zu den Rules unter http:// wiki.ciaweb.net/yawiki/index.php?area=Text_Wiki&page=WikiRules zu finden sind. Die Dokumentation des Pakets unter pear.php.net lässt doch leider ein wenig zu wünschen übrig.
Erwähnenswert ist noch die Rule toc, die für das Erstellen eines Inhaltsverzeichnisses zuständig ist. toc verfügt über verschiedene Schlüssel, mit denen den einzelnen Elementen des Inhaltsverzeichnisses eine Formatierung zugewiesen werden kann. Wichtig ist hierbei der Schlüssel title. Mit seiner Hilfe können Sie die Überschrift für das Inhaltsverzeichnis definieren. Die normale Ausgabe Table of Contents könnten Sie mit
durch den Text Inhaltsverzeichnis ersetzen.
Im Manual werden Sie auch noch einige Regeln finden, die sich nicht auf Tags, sondern auf das globale Konvertierungsverhalten beziehen. Das Verhalten dieser so genannten Filter wird üblicherweise nicht mit setRenderConf(), sondern mit setParseConf() festgelegt, da sie nicht erst beim Rendern, sondern schon beim Parsen des Textes genutzt werden.
Fehlt nur noch ein letzter Punkt, damit Sie ein Wiki auf Basis dieses Pakets erstellen können: Wiki-Links und InterWiki-Links. Hiermit werden Links bezeichnet, die auf eine andere Seite im selben Wiki bzw. auf Seiten in anderen Wikis verweisen. Diese Links werden innerhalb des Textes dadurch gekennzeichnet, dass Wörter direkt hintereinander geschrieben werden wie beispielsweise LinkZurSeite. In diesem Fall erscheint auch der Text »LinkZurSeite« auf der fertig gerenderten Seite. Um dem User einen anderen Text zu zeigen, geben Sie den Link in eckigen Klammern an und schreiben den gewünschten Text direkt dahinter, wie in diesem Beispiel: [LinkZurSeite Beschreibung des Links]
Damit das System das in einen sinnvollen Link umwandeln kann, fehlt aber noch die Information, welche URL der Server hat. Diese muss dem System mithilfe von setRenderConf() mitgeteilt werden. Hierbei ist wikilink die Rule und view_url der Schlüssel, der gesetzt werden muss.
Ein Link hätte dann das Format http://example.com/show.php?seite =LinkZurSeite. Dies ist der übliche Aufbau für Links in Wikis. Mit rein statischen Seiten wird nicht gearbeitet, wobei ein Caching der einmal erstellten Seiten sinnvoll ist. Damit die Links nicht ins Leere laufen, müssen Sie dem System auch noch mitteilen, welche Seiten denn überhaupt existieren. Hierzu muss dem Schlüssel pages noch ein Array mit existierenden Seiten übergeben werden:
$seiten = array('HomePage', 'LinkZurSeite', 'AndereSeite'); $wiki->setRenderConf('Xhtml', 'wikilink', 'pages', $seiten);
Eine ähnliche Vorgehensweise gilt für InterWiki-Links. Diese setzen sich allerdings immer aus einem Server- und Seitennamen zusammen, wie beispielsweise DerServer:DieSeite. Auch hierbei können Sie einen erklärenden Text mit angeben, wenn Sie mit eckigen Klammern arbeiten: [DerServer:DieSeite Hier geht’s zum anderen Wiki]. Auch hier muss der Renderer wissen, wie die URL des Servers lautet, was mit
$sites = array( 'MeatBall' => 'http://www.usemod.com/cgi-bin/mb.pl?%s', 'Advogato' => 'http://advogato.org/%s', 'MyWiki' => 'http://c2.com/cgi/wiki?%s' ); $wiki->setRenderConf('Xhtml', 'interwiki', 'sites',$sites
festgelegt wird. Der Schlüssel sites aus der Rule interwiki bekommt ein Array mit einer Kombination aus Wiki-Namen und URLs übergeben. Bitte beachten Sie das %s am Ende der URL. Das wird für die Ausgabe benötigt und wird durch den Seitennamen ersetzt. Welche Seiten auf dem Ziel vorhanden sind, müssen Sie bei InterWiki-Links nicht definieren.
Text_Wiki ist alles in allem ein sehr leistungsfähiges Paket, das vielfältigste Möglichkeiten bietet. Sollten Sie es nutzen wollen, möchte ich nochmals auf die externe Homepage des Pakets hinweisen, die wirklich sehr hilfreich ist.
