Dokumentation der StringParser_BBCode-Klasse

2. Definieren von eigenem BBCode

2.1 Einbinden der Klasse

Um die Klasse verwenden zu k�nnen, m�ssen zuerst die beiden Dateien stringparser.class.php und stringparser_bbcode.class.php in ein gemeinsames Verzeichnis kopiert werden. Die Datei stringparser_bbcode.class.php muss nun im eigenen PHP-Script eingebunden werden:

<?php
require_once 'pfad/zu/stringparser_bbcode.class.php';
// weiterer PHP-Code
?>

Nun steht die Klasse zur Verf�gung. Um sie nutzen zu k�nnen, muss ein Objekt der Klasse erzeugt werden. Dies geschieht so:

<?php
require_once 'pfad/zu/stringparser_bbcode.class.php';

$bbcode = new StringParser_BBCode ();
// weiterer PHP-Code
?>

Somit ist die Klasse in das PHP-Script eingebunden und einsatzbereit.

2.2 Der erste Code

Um mit der Klasse einen Code zu definieren, verwendet man die Methode addCode. Nun soll folgender Code definiert werden:

Dazu muss folgender Aufruf verwendet werden:

<?php
require_once 'pfad/zu/stringparser_bbcode.class.php';

$bbcode = new StringParser_BBCode ();

$bbcode->addCode ('b', 'simple_replace', null, array ('start_tag' => '<b>', 'end_tag' => '</b>'),
                  'inline', array ('block', 'inline'), array ());

// weiterer PHP-Code
?>

Die Methode addCode ist wie folgt definiert:

void addCode (string $code, string $type, string $callback, string $params, string $content_type,
              array $allowed_in, array $not_allowed_in);

Hier sind alle Parameter des addCode-Aufrufs noch einmal zusammen mit einer Erkl�rung aufgef�hrt:

$code (im Beispiel 'b')
Das ist der Name des Codes. Damit soll ausgedr�ckt werden, dass nach [b] gesucht werden soll. Falls dieser Parameter 'fangmich' w�re, w�rde nach [fangmich] gesucht werden.
$type (im Beispiel 'simple_replace')
Das ist die Art, wie der Code behandelt werden soll. 'simple_replace' bedeutet, dass der Starttag (also [b]) und der Endtag (also [/b]) einfach durch feste Zeichenketten ersetzt werden sollen. Weiter unten mehr zu den Behandlungsarten.
$callback (im Beispiel null)
Hier w�rde eine Funktion angegeben werden, die bei dem Ersetzen aufgerufen wird. Da f�r die Behandlungsart 'simple_replace' keinerlei Funktionen notwendig sind, kann man hier getrost null angeben, er wird in diesem Fall schlichtweg nicht ausgewertet.
$params (im Beispiel array ('start_tag' => '<b>', 'end_tag' => '</b>'))
Dieser Parameter beinhaltet eigentlich Werte, die der Funktion mit �bergeben werden, sobald sie aufgerufen wird. Da hier keine Funktion notwendig ist, werden hier stattdessen direkt die Ersetzungen angegeben, die verwendet werden sollen.
$content_type (im Beispiel 'inline')
Dies ist er Inhaltstyp dieses Codes.
$allowed_in (im Beispiel array ('block', 'inline'))
Dieser Parameter gibt an, innerhalb von welchen Inhaltstypen sich der Code befinden darf. Falls der Code innerhalb eines anderen Inhaltstyps angetroffen wird, wird er ignoriert. Bei diesem Parameter werden allerdings nur der Inhaltstyp des Codes, in dem sich der aktuelle Code gerade befindet, betrachtet.
$not_allowed_in (im Beispiel array ())
Dieser Parameter gibt an, innerhalb von welchen Inhaltstypen sich der Code auf keinen Fall befinden darf. Hierf�r werden die Inhaltstypen aller Elemente betrachtet, in denen sich der Code befindet. Wird auch nur eines gefunden, in dem der Code nicht erlaubt ist, wird der Code ignoriert.

2.3 Behandlungsarten

Die Klasse kann auf Codes unterschiedlich reagieren. Dazu gibt es die sogenannten Behandlungsarten.

'simple_replace'
Bei dieser Behandlungsart werden Start- und End-Tags einfach durch feste Zeichenketten ersetzt. [b] kann man beispielsweise durch <b> ersetzen lassen und [/b] durch </b>. Bei dieser Behandlungsart sind keinerlei Attribute m�glich. Die Zeichenketten, die zum Ersetzen verwendet werden, m�ssen in $params['start_tag'] und $params['end_tag'] stehen, siehe auch das Beispiel oben.
'simple_replace_single'
Diese Behandlungsart ist wie 'simple_replace', allerdings wird davon ausgegangen, dass es ausschlie�lich den Starttag gibt und keinen Endtag, das Element also nur aus dem Starttag besteht und keinen Inhalt hat. Aus diesem Grund braucht auch nur $params['start_tag'] gesetzt zu sein.
'callback_replace'
Bei dieser Behandlungsart wird eine Funktion aufgerufen, die dann den Text zur�ckliefert, der als Ersetzung verwendet werden soll. Dies wird ausf�hrlich im Kapitel Callback-Funktionen behandelt.
'callback_replace_single'
Wie 'callback_replace', allerdings gibt es auch hier nur einen Starttag.
'usecontent'
Diese Behandlungsart ist im Prinzip 'callback_replace', nur, dass innerhalb des Elements nicht nach weiteren BB-Codes gesucht wird. Eine ausf�hrliche Erkl�rung dazu gibt es im Abschnitt Spezielle Codes.
'usecontent?'

Diese Behandlungsart kann sich entweder wie 'usecontent' oder aber auch wie 'callback_replace' verhalten. Es wird gepr�ft, ob ein bestimmtes Attribut gesetzt ist. Wenn dies der Fall ist, wird 'callback_replace' angenommen. Im anderen Fall wird 'usecontent' angenommen. Der Name des Attributs, nach dem gesucht werden soll, ist in $params['usecontent_param'] anzugeben. Diese Behandlungsart ist beispielsweise f�r den h�ufig verwendeten BB-Code [url] sinnvoll. Dieser kann n�mlich auf zwei verschiedene Weisen verwendet werden: [url]http://www.example.com/[/url] und [url=http://www.example.com/]Linktext, auch noch mit [b]fettem[/b] Text[/url]. Im ersten Fall w�re hier 'usecontent' als Behandlungsart angebracht, da der URL, auf den der Link zeigen soll, als normaler Text zwischen Start- und Endtag angegeben ist und es �berhaupt nicht sinnvoll w�re, innerhalb des URL http://www.example.org/ weitere BB-Codes zu ersetzen. Andererseits w�re im zwieten Beispiel 'callback_replace' als Behandlungstyp angebracht, da hier der URL als Parameter angegeben wurde und der Linktext ja durchaus weitere BB-Codes enthalten d�rfte.

Hinweis: Es ist m�glich, mehrere Parameter als usecontent_param anzugeben, indem man einfach ein Array �bergibt anstelle einer Zeichenkette. Beispiel: $bbcode->addCode (..., array('usecontent_param' => array ('parameter1', 'parameter2')), ...);.

'callback_replace?'
Diese Behandlungsart ist das genaue Gegenteil von 'usecontent?' - wenn einer der Attribut, die in usecontent_param angegeben wurden, existiert, wird der Code wie 'usecontent' behandelt, ansonsten wie 'callback_replace'.

2.4 Parsen von Text

Um nun einen Text umzuwandeln, muss man die parse-Methode der Klasse aufrufen:

// Code, um die Klasse einzubinden, addCode-Aufrufe, etc.

$neuer_text = $bbcode->parse ($alter_text);

Somit wird der Inhalt von $alter_text verarbeitet und das Ergebnis ist dann in $neuer_text enthalten. Die Methode parse kann beliebig oft hintereinander aufgerufen werden, allerdings wird sie immer sofort false zur�ckgeben, wenn gerade noch ein Parsevorgang am Laufen ist.