Kapitel 21 Mambots erstellen

Im Gegensatz zu Modulen operieren Mambots zumeist direkt am eigentlichen Inhalt. Technisch gesehen werden sie in Abhängigkeit von verschiedenen Vorfällen (Events) im Hauptprogramm aufgerufen. Ein solcher Event ist beispielsweise die Vorbereitung eines Inhaltselements für die Ausgabe. Ein anderes kann der Aufruf des Editors sein.

Mambots tauchen, wie bereits erwähnt, in vier verschiedenen Formen auf. Sie können erstens direkt den Inhalt verändern, zweitens einen Editor einbinden, drittens über einen Editor-Button eigenen Text einfügen und viertens bei der Suche Ergebnisse zurückliefern. Wir werden uns die einzelnen Ausprägungen mit Ausnahme des eigenen Editors im Folgenden genauer ansehen.

Vieles davon wird Ihnen aus Kapitel 7, Module, Mambots, Komponenten, schon bekannt vorkommen. Auch Mambots benötigen für die Installation eine XML-Datei, über die auch Parameter angegeben werden können. Ebenso ist es aus Mambots heraus möglich, die Funktionen und Objekte der Joomla!-API zu verwenden.

21.1 Mambots für den Inhalt 

Die Aufgabe und Funktion unseres Mambots, den wir »HotLink« nennen wollen, ist es zum einen, eine einfache Funktion für interne Links zur Verfügung zu stellen, und zum anderen, alle externen Links im Inhalt mit einem Symbol als solche kenntlich zu machen. Dieses Symbol soll über einen Parameter auswählbar sein.

Sehen wir uns zunächst einmal die XML-Datei an:

1   <?xml version="1.0" encoding="iso-8859–1"?>
2   <mosinstall type="mambot" group="content" version="1.0">
3     <name>MosHotLink</name>
4     <author>Markus</author>
5     <creationDate>February 2006</creationDate>
6     <copyright>(C) 2006 Markus</copyright>
7     <license>GNU GPL</license>
8     <version>0.1</version>
9     <description>Links im Content</description>
10    <files>
11      <filename mambot="moshotlink">ð
12         moshotlink.phpð
13      </filename>
14    </files>
15    <params>
16       <param name="image" type="imagelist"
17              label="Symbol" default="globe3.png"
18              directory="/includes/js/ThemeOffice"
19              hide_none="1" hide_default="1"
20              description="Icon für externe Links" />
21       </params>
22  </mosinstall>

In Zeile 2 ist angegeben, dass es sich um einen Mambot der Gruppe content handelt. Nach einigen Meta-Informationen (Zeilen 3–9) werden die Dateien angegeben, die zum Mambot gehören (Zeilen 10–14). In unserem Fall ist das nur die Datei moshotlink.php. Danach wird der einzige Parameter eingeführt, der ein Bildauswahlfeld darstellt, wie wir es schon aus dem Modul kennen.

Im eigentlichen Mambot werden wir uns zunächst der Erstellung interner Links widmen. Diese sollen im Text nach dem Schema

{moshotlink=id}

eingefügt werden können und müssen in die URL index.php?option= com_content&task=view&id=ID umgesetzt werden. Um einen Mambot einsetzen zu können, muss dieser zunächst registriert werden. Wie schon angedeutet, reagieren Mambots auf verschiedene Ereignisse. Die eigentliche Funktionalität wird in eine Funktion verpackt. Das bedeutet, dass wir diese Funktion als Eventhandler eintragen müssen.

1   <?php
2   defined( '_VALID_MOS' ) or die( 'Direct Access to this
3      script is not allowed');
4   $_MAMBOTS->registerFunction( 'onPrepareContent',
5                                'botMosHotLink' );
6   function botMosHotLink( $published, &$row  )
7   {
8      $regex = "/{moshotlink=([^\s]*)\s*name=([^\s]*)}/s";
9      $repl = '<a href="index.php?'
10             .'option=com_content&task=view&id=$1">'
11             .'$2</a>';
12     $row->text = preg_replace($regex, $repl, $row->text);
13     return true;
14  }
15  ?>

Die Zeilen 1–3 verhindern wieder, dass das Skript ohne den Kontext von Joomla! aufgerufen wird. Danach wird als Erstes die neue Funktion botMosHotLink als Eventhandler für das onPrepareContent-Ereignis registriert. Das bedeutet, dass diese Funktion aufgerufen wird, wenn ein Inhaltselement für die Ausgabe vorbereitet wird. Es gibt mehrere dieser Ereignisse, die für uns interessant sein können.

In den Zeilen 6 bis 14 steht die eigentliche Funktion. Diese nimmt in unserem Fall zwei Argumente entgegen: zum einen die Information, ob der Mambot verfügbar ist, und zum anderen eine Variable $rows, die den Text des Content Items enthält. In Zeile 8 wird ein regulärer Ausdruck definiert, der nach Mustern sucht, die mit {moshotlink beginnen. Wichtig ist, dass die runden Klammern so gesetzt sind, dass sie genau die uns interessierende Information, die ID und die Beschriftung des Links, umschließen. In den Zeilen 9–11 wird der Link definiert, der den Mambot-Befehl ersetzen soll. Beachten Sie, dass mit $1 (Zeile 10) und $2 (Zeile 11) auf den Inhalt der oben genannten Klammern zugegriffen wird. Nach diesen Vorbereitungen müssen wir nur noch in Zeile 12 die gerade vorbereitete Ersetzung vornehmen.

Um den Mambot zu installieren, gehen Sie genauso vor, wie wir es in Abschnitt 7.4, Neue Erweiterungen installieren, bereits besprochen hatten. Damit werden die Dateien, die im <files>-Tag der XML-Datei angegeben sind, in das Gruppenverzeichnis unter joomla/mambots kopiert (in unserem Fall joomla/mambots/content), und es wird ein Eintrag in der Datenbank angelegt. Vergessen Sie nicht, unser Programm im Mambot-Manager zu publizieren. Jetzt können Sie es bereits testen. Die weiteren Veränderungen im Programmcode können Sie zu Testzwecken direkt in der Datei joomla/mambots/content/moshotlink.php vornehmen. Wenn Sie die Dateien jedoch neu benennen, müssen sie auch neu installiert werden.

Sie fragen sich vielleicht, warum der Parameter $published an die Funktion übergeben wird. Sollte der Mambot nicht einfach ignoriert werden, falls er versteckt ist? Die Antwort ist, dass einige Mambots, die über Code beispielsweise in geschweiften Klammern aufgerufen werden, diesen aus dem Text entfernen sollten, falls sie nicht aktiv sind. Auch in unserem Projekt ist das der Fall; ansonsten wäre der Text mit lauter {moshotlink} durchtränkt. Daher werden wir die folgenden Zeilen direkt am Beginn der Funktion einfügen:

6   function botMosHotLink( $published, &$row  )
7   {
8      if (!$published) {
9         $row->text = preg_replace( '/{moshotlink[^}]*}/s',
10                                   '', $row->text );
11        return true;
12     }
13     $regex = "/{moshotlink=([^\s]*)\s*name=([^\s]*)}/s";

In Zeile 8 wird abgefragt, ob der Mambot aktiviert ist. Wenn das nicht der Fall ist, so werden in den Zeilen 9 und 10 alle Zeichenketten, die mit {moshotlink beginnen, durch einen Leerstring ('') ersetzt. Zeile 11 beendet dann die weitere Verarbeitung der Funktion.

Die zweite Aufgabe, die wir uns gestellt hatten, soll an jeden externen Link ein Symbol anhängen. Das geht im Prinzip wie oben: Wir brauchen ein Erkennungsmuster für externe Links und eine Ersetzung. Interessant wird die Abfrage der Parameter, die etwas komplexer ist als die der Module. Der Code wird in der Funktion nach den bereits existierenden Befehlen eingefügt.

6   function botMosHotLink( $published, &$row  )
7   {
8      global $database;
...
19     $query = "SELECT id FROM #__mambots"
20              ."WHERE element = 'moshotlink' "ð
21              ."AND folder = 'content'";
22     $database->setQuery( $query );
23     $id = $database->loadResult();
24     $mambot = new mosMambot( $database );
25     $mambot->load( $id );
26     $botParams = new mosParameters( $mambot->params );
27     $image = $botParams->get('image', 'globe3.png');
28     $regex="#(<a\shref=(\"|')http://[^>]*>([^<]*))"
29            ."</a>#s";
30     $repl = '$1<img src="includes/js/ThemeOffice/'
31             .$image.'" border="0"></a>';
32     $row->text = preg_replace($regex, $repl, $row->text);
33     return;
34  }

In Zeile 8 müssen wir uns das global definierte Datenbankobjekt in die Funktion holen. Als Nächstes wollen wir den Wert des Parameters ermitteln. Leider ist dieser nicht einfach in einem bestehenden Objekt verpackt. Daher ist es nötig, ein neues Mambot-Objekt zu erstellen. Dazu brauchen wir die ID des Mambots, die wir aus der Datenbank beziehen. Die SQL-Abfrage, die das erledigt, wird in den Zeilen 19 – 21 vorbereitet und in Zeile 23 ausgeführt. In Zeile 24 wird ein neues Mambot-Objekt erstellt und in Zeile 25 mit Werten aus der Datenbank gefüllt. Nun können wir in Zeile 26 ein neues Parameter-Objekt erzeugen, das mit den Parametern des Mambots verbunden wird. Ab Zeile 27 gehen die Dinge wieder ihren gewohnten Lauf. Wir holen zunächst den Wert des Parameters image in die Variable $image. Dann definieren wir ein Suchmuster, das alle Zeichenfolgen findet, die mit <a href="http:// beginnen und mit </a> enden. Das Suchmuster hat eine runde Klammer, die genau bis zum </a>-Tag reicht. Das heißt, im Ersetzungsmuster in Zeile 30/31 können wir diesen Bereich mit $1 ansprechen und übernehmen. Dahinter geben wir das Bild aus und danach erst das neue </a>-Tag. Die Ersetzung findet dann in Zeile 32 statt.