Von allen guten und bösen Geistern verlassen

Eigene Shortcodes in WordPress

WordPress lässt sich an vielen Stellen erweitern. Durch Funktionen des gewählten Themes genau so wie durch Plugins. Oft gibt es aber gerade in der täglichen redaktionellen Arbeit mit WordPress Dinge, die man abkürzen kann.

Wenn man zum Beispiel immer einen ganz bestimmte Redewendung unter seine Artikel schreibt. Oder aufwändigere Formatierungen einfach haben möchte. An dieser Stelle kommen die so genannten Shortcodes ins Spiel.
Eigene Shortcodes können in WordPress entweder über die Datei functions.php des Themes festgelegt werden oder aber via Plugin. Sind die Shortcodes Bestandteil des Themes, haben sie keine Gültigkeit mehr, wenn ein anderes Theme ausgewählt wird.

Einfache Shortcodes

Die einfachste Art ein Shortcode hinzufügen über eine zusätzliche Funktion im Theme (Datei functions.php):

function hallo_koeln_shortcode() {
    return "Hallo Köln!";
}

add_shortcode('koeln', 'hallo_koeln_shortcode');

Über [koeln] wird der Rückgabewert der Funktion hallo_koeln_shortcode in einen Beitrag oder eine Seite eingebunden. Entscheidend dafür ist der Hook add_shortcode über den die Funktion an WordPress gebunden wird.

Da dieser Hook die Nutzung des Shortcodes auf Beiträge und Seiten beschränkt, muss für die Verwendung innerhalb von Widgets ein weiterer Hook verwendet werden:

add_filter('widget_text', 'do_shortcode');

Mit dem Filter der den Inhalt von Widgets angewendet wird, sind alle in einer WordPress Installation verfügbaren Shortcodes in Widgets ausführbar.

Shortcodes mit Parametern

Um Parametern an die eigene Shortcode-Funktion zu übergeben, werden diese als Array an erster Stelle im Kopf der Funktion erwartet:

function hallo_deine_stadt($atts) {
    
    $atts = shortcode_atts( array(
        'ist' => 'Schilda',
    ), $atts, 'deinestadt' );
    
    
    return "Hallo ".$atts['ist'].'!';
}

add_shortcode('deinestadt', 'hallo_deine_stadt');

Die Parameter sollten in jedem Fall über die Funktion von WordPress ausgelesen und mit Default-Werten versehen werden für den Fall, dass der entsprechende Shortcode ohne Parameter verwendet wurde. In diesem Fall würde beim Aufruf von [deinestadt ist=’Köln‘] Hallo Köln! ausgegeben. Wird der Shortcode [deinestadt] ohne Parameter verwendet, nutzt WordPress den über shortcode_atts festgelegten Default-Wert, was zur Ausgabe von Hallo Schilda! führt.

Das Array $atts kann weitere Parameter enthalten, die dann auch ausgelesen werden können (und zuvor mit Default-Werten versehen werden sollten):

function hallo_deine_stadt($atts) {
    
    $atts = shortcode_atts( array(
        'ist' => 'Schilda',
        'wie' => 'schön',
    ), $atts, 'deinestadt' );
    
    
    return 'Wie '.$atts['wie']
       .' das du in '.$atts['ist'].' wohnst!';
}

add_shortcode('deinestadt', 'hallo_deine_stadt');

Um die Rückgabe der Werte noch etwas eleganter zu gestalten, kann die PHP-Funktion extract verendet werden:

function hallo_deine_stadt($atts) {

    extract(shortcode_atts( array(
        'ist' => 'Schilda',
        'wie' => 'schön',
    ), $atts, 'deinestadt' ));
    
    return 'Wie '.$wie.' das du in '.$ist.' wohnst!';
}

add_shortcode('deinestadt', 'hallo_deine_stadt');

Bei der Verwendung des Shortcodes spielt es im Übrigen keine Rolle, in welcher Reihenfolge die Parameter gesetzt werden. Sowohl [deinestadt ist='Wesel' wie='blöd'] als auch [deinestadt wie='blöd' ist='Wesel'] sind gültig und führen zum gleichen Ergebnis.

Umschließende Shortcodes

Neben der flexiblen Übergabe von Parametern können auch Inhalte an die Funktion übergeben werden, wenn diese von dem Shortcode umschlossen werden. Als zusätzlicher Variable in der Funktion wird dann $content verwendet:

function cato_shortcode($atts,$content) {
 
 return '<blockquote class="cato">'.$content.'<br /><small>Cato Censorius (234 v. Chr.; † 149 v. Chr.)</small></blockquote>';
}

add_shortcode('cato', 'cato_shortcode');

Auch wenn in diesem Beispiel keine Attribute verwendet werden, muss die Variable $atts gesetzt werden.

Verwendung von Shortcodes direkt im Theme

Um ein Shortcode direkt in einer Template-Datei eines Themes nutzen zu können, gibt es WordPress die Funktion do_shortcode()- Übergeben wird als Parameter genau das, was in einem Beitrag oder einer Seite verwendet wird:

<?php echo do_shortcode('[cato] Programmierer müssen belohnt werden.[/cato]'); ?>

Shortcode Plugin

Um einen definierten Shortcode auch beim Wechsel des Themes weiterverwenden zu können, ist es besser, ihn statt in der Datei functions.php unterzubringen ein Plugin dafür zu schreiben. Das Beispiel mit dem Cato Zitat würde als eigenes Plugin wie folgt aussehen:

<?php
/*
Plugin Name: Cato Zitat
Description: Stellt dem Shortcode [cato]ZITAT[/cato] zur Verfügung.
Author: Thomas Boley
Version: 1
Author URI: https://www.wildbits.de
*/

class cato {

 function __construct() {
 add_shortcode('cato', array( $this, 'cato_shortcode' ));
 add_filter('widget_text', 'do_shortcode');
 }
 
 function cato_shortcode($atts,$content) {
 return '<blockquote class="cato">'.$content.
 '<br /><small>Cato Censorius (234 v. Chr.; † 149 v. Chr.)</small></blockquote>';
 }

}

$cato = new cato;
?>

Im Kommentar am Anfang des Codes stehen Angabe, die für die Verwendung von WordPress Plugins wichtig sind und den Konventionen für die Benennung entsprechen. Das Plugin selber besteht aus einer Klasse mit dem Namen „cato“ und enthält als erste Methode Konstruktor — eine function, die immer dann aufgerufen wird, wenn ein neues Objekt aus dieser Klasse erstellt wird. Hier würde bei Aktivierung des Plugins entsprechend der Shortcode über add_shortcode() hinzugefügt werden. An add_shortcode werden laut Codex üblicherweise zwei Parameter übergeben: $tag und $func. Im Falle von $func ist die Konstruktion array( $this, 'cato_shortcode' ) notwendig, damit PHP (und WordPress) weiss, dass die aufzupfende Funktion für den Shortcode eine Methode des aus der Klasse erzeugten Objekts ist. Die eigentlich Funktion für den Shortcode ist identisch zu der Version, die zuvor in der Datei functions.php verwendet wurde.

Als letzte Anweisung außerhalb der Klasse benötigt das WordPress Plugin noch eine Anweisung, die ein neues Objekt der Klasse instanziert.

Zusammenfassung

Ein eigenen Shortcode mit etwas PHP selber festzulegen, ist im Grunde garnicht so schwer. Durch ein paar Zeilen spart man sich zudem ein zusätzliches Fremd-Plugin und ist auch in Bezug auf die Anpassungsmöglichkeiten wesentlich flexibler. Ob man dabei wirklich selber ein Plugin schreibt oder den Weg über die Datei functions.php geht, ist letztendlich fast nur eine Geschmacksfrage.

Eine Antwort

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.

DSGVO Cookie Consent mit Real Cookie Banner