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.