MFG mit freundlichen Grüßen

Shortcodes – nützliche Helfer

Deutsch ist eine schöne Sprache. Durch geschickte Aneinanderreihung von Begriffen bilden wir Ausdrücke, die sehr präzise Dinge beschreiben. Allerdings entstehen dabei Wortungetüme wie das Bundes­aus­bildungs­förderungs­gesetz, das uns unter seiner Abkürzung BAföG besser bekannt ist. Wer vermutet, dass sich hinter der Abkürzung NMU eine Nahrungs­mittel­unver­träg­lich­keit versteckt oder BUZ die Abkürzung für die Berufs­unfähig­keits­zusatz­ver­sicherung ist? Letztere sollte vorsorglich abgeschlossen werden, wenn man ähnlich lange Begriffe häufig schreiben muss; Tippfehler sind vorprogrammiert.

Zum Glück gibt es ja Textbausteine. Textbausteine sind so alt wie die Textverarbeitung auf Computern und können nicht nur lange und kompliziert zu schreibende Wörter, sondern auch ganze Textpassagen ersetzen – Formatierung inklusive.

Auch WordPress verwendet Textbausteine, nur heißen sie hier Shortcodes. Bereits in WordPress Version 2.5 wurde die Shortcode API geschaffen, mit der die Eingabe wiederkehrender Textabschnitte vereinfacht werden soll.

Die API funktioniert so, dass in einem Plugin ein Shortcode einmalig festgelegt wird und dann an beliebiger Stelle in Seiten und Beiträgen verwendet werden kann. Die Eingaben erfolgt in eckigen Klammern, also z.B. als [helloworld]. Wird die Seite oder der Beitrag anschließend von Webseitenbesuchern aufgerufen, wird der Beitragsinhalt gefiltert und dabei jeder Shortcode durch den in einer Funktion hinterlegten Text ersetzt.

Aber werfen wir doch einen Blick hinter die Kulissen:

[wpforum] – einfache Shortcodes

Nehmen wir an, wir möchten gerne an verschiedenen Textstellen den Link zum deutschsprachigen WordPress Support-Forum angeben. Dabei möchten wir außerdem angeben, dass Suchmaschinen dem Link nicht folgen sollen. Der Link sieht also so aus:

<a href="de.wordpress.org/support" rel="nofollow">WordPress Support-Forum</a>Code-Sprache: HTML, XML (xml)

Damit wir uns künftig bei der Eingabe nicht mehr die Finger verhaken, definieren wir einen Shortcode. Die von der API zur Verfügung gestellte Funktion heißt add_shortcode() und verfügt über zwei Parameter,

1. die Bezeichnung des Shortcodes und
2. die Funktion, die durch diesen Shortcode ausgeführt werden soll.

Als Bezeichnung für den Shortcode verwenden wir einen leicht zu merkenden Begriff: wpforum.

Die Funktion nennen wir kp_forumlink, wobei wir eine Vorsilbe vorangestellt haben (hier kp_ für … – genau, krautpress.de), damit es später nicht zu Konflikten mit gleichen Funktionsnamen in anderen Plugins kommt.

Unser Code sieht jetzt so aus:

add_shortcode( 'wpforum', 'kp_forumlink' );Code-Sprache: PHP (php)

Als nächstes fügen wir die Funktion hinzu, die ausgeführt werden soll, wenn der Shortcode in einem Beitrag gefunden wird:

function kp_forumlink() {
	$ausgabe = '<a href="de.wordpress.org/support" rel="nofollow">WordPress Support-Forum</a>';
	return $ausgabe;
}Code-Sprache: PHP (php)

Die erste Zeile unserer Funktion weist hier den Text, den wir gerne einsetzen möchten, einer Variablen $ausgabe zu.

Die nachfolgende Anweisung return $ausgabe; gibt diesen Text an die Funktion zurück, die den Text filtert und aufbereitet.

Häufiger Anfängerfehler ist übrigens, statt return die PHP-Funktion echo zu verwenden. Dies führt zu einer vorzeitigen Ausgabe (englisch echo) bei Aufruf der Funktion, während doch eigentlich eine Übergabe (englisch return) an die Funktion zur Filterung des Textes gewünscht ist; mit echo erscheint der Text an der falschen Stelle.

Merksatz: Bei Shortcodes nie echo verwenden.

Mittlerweile sieht unser Code folgendermaßen so aus:

add_shortcode( 'wpforum', 'kp_forumlink' );
function kp_forumlink() {
	$ausgabe = '<a href="de.wordpress.org/support" rel="nofollow">WordPress Support-Forum</a>';
	return $ausgabe;
}Code-Sprache: PHP (php)

Diesen Code können wir nun erst einmal in der functions.php unseres Child Themes anhängen und gleich ausprobieren, ob nach Eingabe von [wpforum] in einer Seite oder Beitrag im Frontend der vollständige Link ausgegeben wird.

[hello name=“Dolly”] – Shortcodes mit Attributen

Die Verwendung von add_shortcode() mit Angabe der Shortcode-Bezeichnung und einer Funktion, die den eigentlichen Text zurückgibt, ist verblüffend einfach.

Allerdings müssten wir nach dem, was wir bisher besprochen haben, zu jeder unterschiedlichen Text-Variante einen neuen Shortcode definieren. Die Shortcode API erlaubt aber auch die Verwendung von Attributen, die Eingabewerte an die Funktion durchreichen:

Bei [hello name="Dolly"] ist hello der Name des Shortcodes, während name ein Attribut ist und Dolly der Wert, der an die Shortcode-Funktion übergeben werden soll.

Als erstes müssen wir wieder einen neuen Shortcode hinzufügen und ihm eine Funktion zuweisen:

add_shortcode( 'hello', 'kp_sag_hallo' );Code-Sprache: PHP (php)

Attribute und die zugehörigen Werte werden in WordPress als assoziatives Array abgespeichert. $atts ist die Variable für das Array aller verwendeten Attribute, name der Index eines bestimmten Attributs und Dolly der diesem Attribut zugewiesene Wert, der bei Abruf von $atts[name] ausgegeben wird.

function kp_sag_hallo( $atts ) {
	$ausgabe = "Oh, hello, $atts[name]";
	return $ausgabe;
}Code-Sprache: PHP (php)

Vorgabewerte für Shortcode-Attribute

Bei meinem letzten Beispiel habe ich (aus didaktischen Gründen) ein wenig geschummelt. Gibt der Anwender Attribute oder deren Werte nicht mit ein und der im Beitrag eingefügte Shortcode lautet nur [hello] oder [hello name=], gibt die Funktion kp_sag_hallo() einen Fehler aus, weil es keinen Vorgabewert gibt.

Hier kommt eine letzte wichtige WordPress-Funktion der Shortcode API ins Spiel:

shortcode_atts( $defaults_array, $atts )Code-Sprache: PHP (php)

Der erste Parameter dieser Funktion ($defaults_array) beschreibt Vorgabewerte, während der zweite Parameter angibt, welche Variable die Shortcode-Attribute enthält.

Als Beispiel wollen wir hier “Dolly” als Vorgabewert für das Attribut name festlegen:

function kp_sag_hallo( $atts ) {
	$werte = shortcode_atts( array(
		'name' => 'Dolly',
	), $atts);
	$ausgabe = "Oh, hello, $werte[name]"
	return $ausgabe;
}Code-Sprache: PHP (php)

Wird im Beitrag nun der Shortcode [hello name="Sweatheart"] eingegeben, wird Oh, hello, Sweatheart ausgegeben. Lautet der Shortcode nur [hello] bzw. [hello name=], wird der Vorgabewert verwendet und Oh, hello Dolly ausgegeben – natürlich ohne Fehlermeldung.

Durch die Nutzung von Shortcodes mit Attributen lassen sich auch komplexe Funktionen in Beiträge und Seiten einfügen. Auch Plugins wie das beliebte Kontaktformular-Plugin Contact Form 7 nutzen Shortcodes, z.B. um ein Kontaktformular im Inhalt einer Seite einzubetten:

[contact-form-7 id="1042" title="Kontaktformular"]Code-Sprache: HTML, XML (xml)

Umschließende Shortcodes

Der Vollständigkeit halber möchte ich noch erwähnen, dass Shortcodes aus so verwendet werden können, dass sie Text umschließen. (Wem es hier zu kompliziert wird, der mag diesen Abschnitt gerne überspringen.)

Umschließende Shortcodes sind z.B. hilfreich, wenn Textabschnitte in bestimmte ein HTML-Gerüst eingebettet werden soll, etwa um Text mehrspaltig oder in verschiedene Tabs zu setzen. Dabei werden dem Shortcode keine Attribute weitergegeben, sondern der Inhalt selbst wird in Shortcodes verschachtelt:

[wichtig]Dieser Text soll hervorgehoben werden![/wichtig]Code-Sprache: HTML, XML (xml)

Zur Formatierung haben wir dazu bereits im Stylesheet eine CSS-Klasse .wichtig angelegt:

.wichtig {
	color: red;
	background-color: yellow;
	font-weight: bold;
	padding: 20px;
}Code-Sprache: CSS (css)

Jetzt definieren wir einen neuen Shortcode und übergeben in der zugehörigen Funktion den Parameter $content:

add_shortcode( 'wichtig', 'kb_wichtig' );
function kb_wichtig( $atts, $content = null ){
	$ausgabe = '<div class="wichtig">' . $content . '</div>';
	return $ausgabe;
}Code-Sprache: PHP (php)

Ähnlich wie bei den Attributen wird mit $content = null für den Fall vorgesorgt, dass die weitergegebene Variable $content leer ist. Existiert jedoch zwischen dem einführenden und schließenden Shortcode ein Inhalt, wird dieser als Wert verwendet.

Wer nicht selber programmieren, aber die zahlreichen Möglichkeiten zur Formatierung nutzen möchte, die sich hieraus ergeben, sollte sich das Plugins Shortcodes Ultimate ansehen. Dieses Plugin erweitert WordPress mit mehr als 40 Shortcodes, die unter anderem Slider und Akkordeon-Animationen, Lightbox-Effekte und QR-Codes hinzufügen.

Shortcodes auch in Widgets nutzen

Shortcodes funktionieren prima in Seiten und Blogbeiträgen, aber nicht ohne weiteres in Text-Widgets. Möchte man Shortcodes auch in Text-Widgets verwenden, hilft folgender, ergänzender Code in der functions.php oder einem Plugin:

add_filter( 'widget_text', 'do_shortcode' );Code-Sprache: PHP (php)

Spannende Sache: mal rasch ein eigenes Plugin schreiben

Noch dabei? Prima. Denn jetzt sollten wir noch eine Kleinigkeit korrigieren. Bisher haben wir unseren Shortcode in der functions.php des Themes platziert. Da gehört er aber eigentlich aus zwei Gründen nicht hin:

1. gehen solche Ergänzungen spätestens bei der nächsten Aktualisierung oder einem Wechsel des Themes verloren,
2. wird hier zusätzliche Funktionalität und Gestaltung vermischt, wodurch unsere WordPress-Installation schwierig zu warten ist.

Besser ist es, ein eigenes Plugin zu schreiben.

Wer bei dem Gedanken an ein eigenes Plugin mit erhöhtem Blutdruck reagiert und so etwas schon gar nicht “mal eben” erstellt, sollte sich freuen: Es ist alles viel einfacher, als es zunächst klingt.

Das Plugin, das wir nun schreiben, unterscheidet sich von unseren bisherigen Code-Beispielen nur dadurch, dass wir in einem so genannten Plugin-Header ein paar Meta-Angaben zu unserem Plugin hinzufügen:

<?php
/*
Plugin Name: Shortcode-Sammlung
Description: Nützliche Shortcodes für meine Website
Author: Bego Mario Garde
*/Code-Sprache: PHP (php)

Direkt unterhalb dieser Angaben können wir nun beliebig viele Shortcodes hinzufügen, wobei wir darauf achten, dass Shortcode-Namen und -Funktionen nicht doppelt vorkommen.

Die fertige Plugin-Datei sieht z.B. so aus:

<?php
/*
Plugin Name: Shortcode-Sammlung
Description: Nützliche Shortcodes für meine Website
Author: Bego Mario Garde
*/

// auch in Text-Widgets verwenden
add_filter( 'widget_text', 'do_shortcode' );

// Shortcode "Oh, hello …(Name)"
add_shortcode( 'hello', 'kp_sag_hallo' );

function kp_sag_hallo( $atts ) {
	$werte = shortcode_atts( array(
		'name' => 'Dolly',
	), $atts);

	$ausgabe = "Oh, hello, $werte[name]";
	return $ausgabe;

}Code-Sprache: PHP (php)

Die Datei speichern wir als kp-shortcodes.php in einem Verzeichnis kp-shortcodes ab und komprimieren das Verzeichnis anschließend als .zip-Datei. Nun können wir das Plugin in einer lokalen Testumgebung ausprobieren.

“Houston, wir haben ein Problem.”

Unter Umständen gibt es jetzt doch noch einen kleinen Nervenkitzel. Denn wenn bei der Programmierung des Plugins etwas schief gelaufen ist, bekommen wir nach der Installation (Menü Plugins → Installieren) eine Fehlermeldung oder – noch schlimmer! – sogar einen komplett leeren Bildschirm (White Screen of Death) angezeigt.

Wie an anderer Stelle beschrieben, hilft in solchen Fällen vor allem Ruhe. Erst einmal sollte, sofern Fehlermeldung angezeigt werden, die angegebene Zeilennummer notiert werden. Dadurch vereinfacht sich meistens die Fehlersuche; oft fehlt an der angegebenen Stelle nur ein Komma oder eine Klammer und das Problem lässt sich schnell beheben.

Um die Testumgebung aber erst mal wieder ans Laufen zu bekommen, hilft es schon, in der Testumgebung das Verzeichnis kp_shortcodes zu löschen. Bei dem nächsten Zugriff auf das Backend wird das fehlerhafte Plugin automatisch als deaktiviert erkannt und die Arbeit kann fortgesetzt werden.

Wer sich vor diesen zuletzt genannten Schritten doch ein wenig fürchtet und “nichts kaputt machen” möchte, sollte sich das Plugin Code Snippets anschauen. Mit diesem Plugin können die hier verwendeten Code-Snippets in Eingabemasken eingegeben werden. Ist der Code fehlerhaft, deaktiviert das Plugins den Code selbständig und weist mit Fehlermeldungen auf mögliche Schwachstellen hin.

Nachteil von Shortcodes

Shortcodes sind einfach einzurichten und können den Arbeitsaufwand beim Schreiben von Blogbeiträgen deutlich reduzieren. Shortcodes haben aber auch kleine Nachteile, die ich nicht unterschlagen möchte.

Nachteil Nr. 1: Fragmente im Text

Wird die Shortcode-Funktion gelöscht, verbleiben im Frontend statt des erwarteten Textes unschöne Shortcode-Anweisungen (z.B. [hello name="Dolly"]). Mit Plugins wie Search & Replace können Shortcodes aber wieder gegen herkömmlichen Text ausgetauscht werden.

Nachteil Nr. 2: Kein visuelles User Interface

Während WordPress bereits für viele Formate vom Youtube-Video über Twitter bis zu WordPress-Blogbeiträgen eine Einbettung-Funktion anbietet, mit der die Inhalte direkt im Backend angezeigt werden, erscheinen Shortcodes im Backend weiterhin nur als nichtsagender Text in eckigen Klammern. Hier gibt es mit dem Projekt Shortcake (Shortcode UI) einen recht vielversprechenden Ansatz für ein visuelles User Interface.

Nachteil Nr. 3: Double Content in Suchmaschinen

Ein Kunde bat mich um Hilfe bei der Erstellung eines Shortcodes, der eine Sammlung von Schlüsselwörtern zu seinem Berufszweig und Geschäftsort wiedergeben sollte. Ziel war, das Suchmaschinenranking zu erhöhen, indem der Shortcode unter jeden Beitrag gesetzt wurde. Solchen Schabernack erkennen Suchmaschinen allerdings. Ganze Textabschnitte, die gezielt wiederholt verwendet werden, um das Suchmaschinenranking zu beeinflussen erreichen aber genau das Gegenteil. Shortcodes sind sehr sinnvoll, wenn häufig genutzte Begriffe damit effizienter eingegeben oder Funktionen eingefügt werden. Als „SEO-Tool“ sind sie aber sicher der falsche Ansatz.

Welche Verwendungszwecke fallen Dir ein?
Mir bleibt für heute nur ein [VG] und [biba].