Einfaches Plugin für Yellow schreiben

Plugin für Datenstrom Yellow erzeugen

Entsprechend der Dokumentation des CMS, werden Plugins Erweiterungen (extensions) genannt und auch in dem namensgleichen Ordner abgelegt. Daher wird eine neue PHP-Datei:

/system/extensions/shortcode.php

angelegt. Dieses Beispielplugin soll einen Shortcode im Text in eine entsprechende Ersetzung umwandeln, die es aus der Datei:

/system/extensions/yellow-system.ini

zum Zeitpunkt des parsens aus dem MD-Format in das HTML-Format läd.

Namensvorschrift für das Yellow Plugin

Das Yellow CMS erlaubt Plugins nach einer bestimmten Namensvorgabe. Folglich muss der Klassen-Name des Plugin identisch mit dem Namen der PHP Datei im Verzeichnis extensions sein und den Zusatz yellow haben. In etwa so:

...
class YellowShortcode {
    const VERSION = "0.8.23";                                // diese Angabe ist optional
    public $yellow;
    ...

Der Klassen-Name lautet also Yellow+Dateiname (ohne .PHP):

class YellowShortcode...

Das Yellow Framework versucht beim Start des Systems alle PHP-Programme im Verzeichnis extensions zu laden, daher muss das Plugin nicht dediziert am System angemeldet oder installiert werden. Die Existenz eines neuen Plugins in diesem Ordner reicht aus, um es nutzen zu können - sofern die Namensvorschrift eingehalten wird.

Das Yellow Plugin

Nun der vollständige Democode des kleinen Yellow Plugins mit Beschreibung der Funktionsweise:

001  <?php
002      class YellowShortcode {
003          const VERSION = "0.8.23";                       // ist optional
004          public $yellow;                                 // die API laden
005  
006          public function onLoad($yellow) {               // bei System-Event
007              $this->yellow = $yellow;                    // die API zwischenspeichern
008          }
009  
010          public function onParseContentShortcut($page, $name, $text, $type) {
011              return $this->yellow->system->get($name);   // Key Value Paar aus ini lesen
012          }
013      }
014  ?>

Zeile 002 legt den Klassen-Namen entsprechend der Yellow Namensregel fest. Die Angabe der folgenden Versionsnummer ist obligatorisch und kann natürlich auch entfallen.

Zeile 004 Erzeugt die öffentliche Klassenvariable yellow, die werden wir in der folgenden Methode brauchen, da in ihr die API des CMS steckt. Die Methode bekommt sie beim Event onLoad() vom Yellow Framework übermittelt, wir müssen sie entgegen nehmen und speichern, um auf die vielen Funktionen des CMS zugreifen zu können.

Zeile 010 wird in dem Moment aufgerufen, wenn Yellow damit beginnt den Text-Inhalt des Markdown-Formates zu parsen. Es wird nach Brackets, also Begriffen in eckigen Klammern gesucht und versucht diese zu interpretieren. In diesem Beispiel verwende ich den Shortcode

[werbebanner]

den ich irgendwo im Text (ohne HTML-Tags rechts oder links) des Beitrags platzieren kann und der dann durch eine passende Ersetzung aus der yellow-system.ini ausgetauscht wird.

Zeile 011 greift auf die yellow-system.ini zu und ermittelt den gefundenen $namen (das ist in diesem Fall ist es [werbebanner]) und sucht den Schlüssel in der ini-Datei. Als Return wird das Value zu werbebanner an den Parser zurüchgesendet und die Ersetzung erscheint im Text statt des Shortcodes. In $name steckt der im Text durch das Yellow gefundene Shortcode ohne eckige Klammern, also werbebanner.

Anlegen einer Ersetzung in der yellow-system.ini

Zum Schluss muss die Angabe des einzeiligen Key-Value-Paares für diesen Shortcode angelegt werden. Öffnen Sie einfach die yellow-system.ini und tragen am Ende die folgende Zeile nach:

...
werbebanner: <p>Einfaches Werbebanner mit <a href="#">Kaufen...</a> Link</p>
...

Platzieren Sie nun den Shortcode irgendwo im Text, erscheint der Inhalt des Schlüssels werbebanner im Text als HTML-Ersetzung.

Das kleine Demoplugin versetzt Sie in die Lage beliebige Shortcodes im laufenden Text anzulegen und diese dann später durch Ersetzungen aus der yellow-system.ini austauschen zu lassen. Allerdings gibt es Regeln für die Vergabe von Shortcodes. Diese dürfen keine Leerzeichen oder Bindestriche enthalten, ein einzelnes Wort oder Unterstriche sind erlaubt. Der Eintrag in der INI-Datei muss ausschließlich einzeilig sein, Umbrüche sind nicht erlaubt, HTML-Elemente jedoch schon. Der Shortcode selbst darf nicht von HTML-Tags eingeschlossen sein, denn sonst wird der Parser deaktiviert auf dessen Event das Plugin ja reagieren soll.

Wenn Sie mögen, können Sie auch die Definitionen für Ersetzungen in einer der Language-Dateien anlegen statt in der System.ini, Sie müssen dann den Aufruf in Zeile 011 anpassen.

Praxistipp: Auch wenn dieses Demoplugin für Yellow eine durchaus interessante Sache ist, so sollten Sie auf solche Ersetzungen durch Shortcodes verzeichten. Der Content wird dadurch weniger flexibel und Sie können diesen nicht mehr mit anderen CMS austauschen, in denen dieses Plugin fremd ist oder nicht existiert. Machen Sie in Ihren Texten so viel es geht manuell.

Oliver Lohse
2023-02-05
Plugin,Shortcode,Ersetzung
post
5