Onno Gabriel - Entwicklung von WordPress-Plugins

Im vorigen Kapitel wurde gezeigt, wie eigene Funktionen über Hooks an unterschiedlichen Stellen in den WordPress-Code eingebunden werden können. Eine weitere Möglichkeit sind sogenannte Shortcodes, über die Plugin-Funktionen direkt an bestimmten Stellen mit dem Inhalt einer WordPress-Seite verknüpft werden können, beispielsweise an beliebigen Stellen in einem Post.

Ein Shortcode ist eine Zeichenfolge, die in eckigen Klammern direkt im Text mit dem Inhalt eingegeben wird, z.B. [shortcode-name]. Über die Funktion add_shortcode()kann ein solcher Shortcode WordPress bekannt gemacht werden, was dazu führt, dass an Stelle des Shortcodes die Funktion eines Plugins aufgerufen wird:

add_shortcode( string $tag, callable $func )

$tag ist der Name des Shortcodes (erforderlich).

$func ist der Name der mit dem Shortcode zu verbindenden Funktion (erforderlich).

Das folgende einfache Beispiel zeigt die Definition eines eigenen Shortcodes, an dessen Stelle eine eine eigene Plugin-Funktion ausgeführt werden soll:

Sehr flexibel wird der Einsatz von Shortcodes durch die Möglichkeit, der aufzurufenden Funktion zusätzlich eigene Attribute übergeben zu können, zum Beispiel:

[shortcode attribut_1='wert_1' attribut_2='wert_2']

Im Plugin werden diese Attribute einfach der Funktion übergeben:

Die Attibute werden der Funktion dabei in Form eines assoziativen Arrays $attsübergeben, im obigen Beispiel also

$atts = array( 'attribut_1' => 'wert_1', 'attribut_2' => 'wert_2' )

Über die WordPress-Funktion shortcode_atts()können dem Array $attsauch Standardwerte zugewiesen werden, die eingesetzt werden falls die Attribute nicht schon im Shortcode mit Werten versehen wurden:

Shortcodes können weitere Inhalte einschließen, in dem sie um diese Inhalte herum angeordnet werden:

[shortcode-name]Eingeschlossener Inhalt[/shortcode-name]

Der eingeschlossene Inhalt wird dabei der aufzurufenden Funktion als Argument $contentübergeben.

Um beispielsweise einen Textabschnitt in fett auszugeben, kann dies auch über einen Shortcode geschehen. Die durch den Shortcode aufgerufene Funktion fasst dann, wie im folgenden Beispiel gezeigt, den umschlossenen Textabschnitt in das HTML-Tag ein:

In einem Post könnte der so definierte Shortcode wie folgt eingesetzt werden:

Ein [fett]fett geschriebener Text[/fett] dank Shortcodes.

Durch die Funktion text_in_fett()wird dann in der Ausgabe an den Browser Folgendes ausgegeben:

Ein fett geschriebener Text dank Shortcodes.

An der Stelle des Shortcodes fügt WordPress den Rückgabewert der aufgerufenen Funktion in den Seiteninhalt ein. Daher muss dieser Wert stets mit returnzurück gegeben und sollte nicht mit echodirekt ausgegeben werden. Bei letzterer Methode würde der Inhalt meist an der falschen Stelle in dem ausgegebenen HTML-Dokument erscheinen.

Eine Alternative ist, die Ausgabe mittels ob_start()in einem Ausgabepuffer zu speichern und am Ende der Funktion den Inhalt des Puffers mit ob_get_clean()auszulesen und zurück zu geben:

Widgets sind mit einem speziellen Inhalt gefüllte Bereiche auf der WordPress-Webseite. Widgets können abhängig vom Theme nahezu beliebig angeordnet werden – typischerweise in der Seitenleiste, im Footer-Bereich oder auch im Admin-Dashboard – und bilden damit modulare, in sich geschlossene Komponenten. Mit solchen Widgets können auch Nicht-Entwickler ihre Webseiten schnell und einfach um Funktionen erweitern. Ein Plugin kann ein oder auch mehrere solcher Widgets zur Verfügung stellen.

Für das Erzeugen eigener Widgets bietet WordPress die objektorientierte Klasse WP_Widgetan. Ein Widget ist daher technisch gesehen nichts anderes als ein PHP-Objekt der WP_Widget-Klasse, welches einen Seiteninhalt ausgibt, sobald die dafür vorgesehene widget()-Methode aufgerufen wird.

Die Klasse WP_Widget wird über die Datei wp-includes/class-wp-widget.phpzur Verfügung gestellt. Diese PHP-Datei stellt mit ihren vielen Kommentaren selbst eine umfassende und lesenswerte Dokumentation der Widget-Klasse dar.

Ein neues Widget wird erstellt, indem eine eigene Klasse als Erweiterung von WP_Widgetdefiniert wird. Dadurch werden alle für das Widget notwendigen Attribute und Methoden an die neue Widget-Klasse vererbt. Vier der Haupt-Methoden werden mit eigenem Code überschrieben, so wie im Folgenden beispielhaft in der Klasse Mein_Widgetdargestellt:

Im Beispiel kommt die Escape-Funktion zum Einsatz, mit der problematische Zeichen bei der Ausgabe maskiert werden. Diese wird später im Kapitel Absichern von Ausgabedaten beschrieben.

Um WordPress dieses neue Widget bekannt zu machen, wird eine Funktion zur Registrierung dieses Widgets über add_action()an den Hook widgets_initgehängt:

add_action( 'widgets_init', function(){ register_widget( 'Mein_Widget' ); });

Damit steht das Widget im Administrationsbereich unter Design/Widgets zur Verfügung und kann von den Benutzern an die gewünschte Position auf der Webseite platziert werden.

Im Folgenden werden die vier Funktionen der neuen Widget-Klasse genauer beschrieben. Sie dienen dem Erzeugen des neuen Widgets durch den Konstruktor, dem Anzeigen des Widget-Inhaltes, des Formulars zur Widget-Konfiguration und zur Verarbeitung der Konfiguration.

Der Konstruktur wird bei der Registrierung des Widgets aufgerufen. Wie im obigen Beispiel gezeigt, wird dabei lediglich ein Name und eine Beschreibung an den Konstruktur der Elternklasse übergeben.

Die widget()-Methode übernimmt die Ausgabe des Widget-Inhalts. Ihr werden dazu zwei Argumente ( $argsund $instance) übergeben:

$argsist ein assoziatives Array, in dem u.a. HTML-Elemente gespeichert sind, die vor und nach dem Widget und vor und nach dem Widget-Titel eingesetzt werden können 1. Damit wird sicher gestellt, dass das Widget sich nahtlos an verschiedene Themes anpassen kann, denn diese HTML-Elemente werden vom Theme definiert. Ein einfaches Beispiel für das $args-Array:

$args = array( 'before_widget' => '

', 'after_title' => '

Das zweite Argument $instanceenthält ein assoziatives Array mit den Einstellungen für das Widget. Diese werden im Administrationsbereich unter Design/Widgets vorgenommen.

Zum Beispiel enthält $instance['title']den Widget-Titel. Genutzt werden diese Elemente bei der Widget-Ausgabe, zum Beispiel:

Mit der form()-Methode wird im Administrationsbereich ein Formular für die Konfiguration des Widgets erzeugt. Ihr wird als Argument $instanceübergeben, also wie in der widget()-Methode ein Array mit den bisherigen Einstellungen in Form von Schlüssel-Wert-Paaren.

Ausgegeben wird nur der innere Teil des Formulars in Form von Labeln und den Eingabefeldern, denn um den Rest wie das

Der Konstruktor und die Methoden widget(), form()und update()stellen nur die Grundfunkionen des Widgets dar. Zusätzlich kann ein Widget durch beliebige eigene Funktionen erweitert werden. Der Programmcode komplexerer Widgets kann zudem auf mehrere Dateien verteilt werden (siehe folgendes Kapitel), um den Code übersichtlich zu halten.