WP Meetup Hannover, 24. Januar 2013

Frank Staude <frank@staude.net>

Als Shortcodes werden in WordPress Kurzbefehle bezeichnet, die in einer bestimmten Schreibweise innerhalb des Editors im sogenannten Contentbereicht verwendet werden können (und auch an anderen Stellen). Shortcodes werden in eckigen Klammern geschrieben. Die einfachste Form eines Shortcodes besteht nur aus dem Namen des Shortcodes, z.B. [mfg], mächtigere Shortcodes haben ein oder mehrere Parameter mit denen man die Ausgabe des Shortcodes weiter steuern kann, z.B. [download id=123]
Und dann gibt es noch die Möglichkeit das ein Shortcode aus einem öffnenden und einen schliessenden Teil besteht und den dazwischen liegenden Text kapselt, z.B. [info]Das ist der Text dazwischen.[/info]

Diese Befehlsschnipsel können vom Redakteur einfach bei der Eingabe des Textes im Editor verwendet werden und werden bei der Ausgabe des Textes auf der Webseite entsprechend der Implementierung des Shortcodes ersetzt.

WordPress selbst liefert einige Shortcodes mit z.b.caption, gallery oder embed.
Viele Plugins stellen einen (mehr oder weniger großen Teil) Ihrer Funktionalität als Shortcode zur Verfügung, um den Redakteuren eine größtmögliche Gestaltungsfreiheit zu geben, da so die Ausgabe nicht innerhalb des Templates sondern bei der Eingabe des Textes festgelegt wird.

Wofür kann ich das nun nutzen?

Beispiel 1: Der Shortcode [mfg] soll eine Grußformel ausgeben.

Der Redakteur soll mit Hilfe eines des Shortcodes [mfg] eine Grußformel ausgeben können. Die Arbeitserleichterung besteht darin, einen (längeren) Textblock, der ständig gebraucht wird, abzukürzen um so Tipparbeit zu sparen.

Die Benutzung soll sein:

Der Redakteur tippt im Editor [mfg] und auf der Webseite soll ausgegeben werden:

Mit freundlichen Grüßen,
Frank Staude

Dazu sind folgende 2 Schritte nötig.

Erstellen der Funktion die den Text zurück liefert. Ich nenne die Funktion in diesem Beispiel my_mfg_shortcode().
Registrieren der unter Punkt 1 erstellten Funktion als Shortcode mit der add_shortcode() Funktion.

function my_mfg_shortcode() {
    return 'Mit freundlichen Grüßen,<br>Frank Staude';
}

add_shortcode('mfg', 'my_mfg_shortcode');

In WordPress registriert man einen Shortcode mit der Funktion add_shortcode ( shortcode, funktion ) sie nimmt zwei Parameter entgegen, den Namen des Shortcodes den wir registrieren möchten und die Funktion die aufgerufen werden soll, wenn der Shortcode ausgeführt werden soll.
Wir wollen den Shortcode info registrieren und die Funktion die aufgerufen werden soll,nennen wir info_shortcode. Der vollständige Aufruf lautet also
add_shortcode ( ‘Info’, ‘info_shortcode’ );

Wenn wir den Shortcode nun verwenden, sieht das Ergebnis wie erwartet aus.

Beispiel 2: Mit dem Shortcode [info]Text[/info] soll ein Textbereich hervorgehoben werden.

Wir wollen den Redakteur die Möglichkeit geben einen Textblock Rot zu hinterlegen.
Technisch ist es lediglich ein DIV mit entsprechender CSS Formatierung, aber natürlich wollen wir nicht das der Anwender selbst ein öffnendes und schließendes DIV inkl der Klassenangabe im HTML Modus des Editors eingibt. Dazu werden wir den Shortcode [info] anlegen. Die Benutzung durch den Redakteur soll so sein

[info]Dieser Text soll auf roten Grund erscheinen [/info]

Dazu sind folgende Schritte nötig

Erstellen der Funktion die den Text zurückliefert. Ich nenne die Funktion in diesem Beispiel mal my_info_shortcode().
Registrieren der unter Punkt 1 erstellten Funktion als Shortcode mit der add_shortcode() Funktion.
Hinzufügen des CSS Anweisungen.

add_shortcode('info', 'my_info_shortcode');

function my_info_shortcode($attr, $content) {
    return '<div>'.$content.'</div>';
}

Und in die CSS Datei kommt

.infobox {
  background-color: #ff0000;
  border: 1px solid;
  margin-bottom: 10px;
  color: #ffffff;
}

Beispiel 3: Amazon Link mit Angabe der ASIN.

Der Redakteur soll einen Link auf ein Amazon Produkt nur mit Angabe der ASIN und des Linktextes anlegen. Der Aufruf soll sein [amazon asin=“123456“] Linktext [/amazon]

Die Funktion die man per add_shortcode registiert kann 2 Parameter übergeben bekommen, die Attribute und den Content. Der erste Parameter ist ein Assoziatives Array und enthält die Attribute und der zweite Parameter ist der Content, also der Text der zwischen dem öffnenden und dem schliessenden Shorttag steht.
Die ASIN steht also im dem Attribute-Array zur Verfügung.
Daraus ergibt sich folgender Programmcode.

add_shortcode('amazon', 'my_amazon_shortcode');

function my_amazon_shortcode( $attr, $content) {
    return '<a href="http://www.amazon.com/dp/'. $attr["asin"].'">'.$content.'</a>';
}

Natürlich müsste man in einer realen Anwendung noch prüfen ob die ASIN auch übergeben wurde und ggf eine Fehlermeldung statt eines defekten Links ausgeben.

Wo kann ich Shortcodes verwenden?

Theoretisch überall – ggf mit etwas „Handanlegen“. Für das ausführen von Shortcodes ist die Funktion do_shortcode() zuständig. Diese wird per Filter an bestimmte Element gekoppelt, z.B. an das Textfeld des Editor.
Um z.B. direkt in der Templatedatei eines Themes einen Shortcode auszuführen, geht man so vor.

$shortcode = “Dein Text [info] mit Shortcode [/info]“;
echo do_shortcode($shortcode);

Kann ich Shortcodes verschachteln?

Ja, dann muss innerhalb der Funkton die deinen Shortcode implementiert der übergebene Content erneut an do_shortcode() übergeben werden. Die Funktion von Beispiel 2 sähe dann so aus

function my_info_shortcode($attr, $content) {
    return '<div>'. do_shortcode($content) .'</div>';
}

Links?

Die Beschreibung der Shortcode API liegt im Codex unter http://codex.wordpress.org/Shortcode_API

Shortcodes – was ist das und wie kann ich das selbst nutzen?