🛠 So fügen Sie Ihren eigenen Shortcode in WordPress hinzu: add_shortcode()-Aufschlüsselung [+2 Beispiele]

Erstellten Snippet, fügten ihn in functions.php ein und WordPress sagt „cheatin' uh?"? Kommt Ihnen das bekannt vor? Shortcodes, der zentrale Erweiterungsmechanismus von WordPress, und add_shortcode() erschließen ihn in 15 Codezeilen. Doch zwischen „Hello World" und einem realen Szenario liegen einige Fallstricke: return vs. echo, die Parameterreihenfolge des Callbacks und Tag-Konflikte.

Shortcodes erschienen bereits in WordPress 2.5 und sind seither das Fundament des Ökosystems: Kontaktformulare, Galerien, Slider, Ausgabe benutzerdefinierter Felder, all das lebt in eckigen Klammern. add_shortcode() hat sich seit Jahren nicht verändert, und Sie beherrschen die Funktion in einer halben Stunde.

Im Folgenden eine vollständige Aufschlüsselung der Funktion mit zwei einsatzbereiten Beispielen: von einer sich automatisch aktualisierenden Jahreszahl im Footer bis zu einer Liste der Seitenbenutzer.

💡 Kurzüberblick:

• Syntax und Parameter von add_shortcode(), Tag und Callback
• Die Regel: immer return, niemals echo
• Der init-Hook, warum Ihr Shortcode ohne ihn möglicherweise nicht funktioniert
• Zwei Wege der Datenübergabe: Inhalt zwischen den Tags und Attribute
• Einsatzbereiter Code: ein Shortcode für das automatische Jahr und eine Benutzerliste

So funktioniert add_shortcode() in WordPress

Die Funktion add_shortcode() ist der Einstiegspunkt für die Registrierung eines beliebigen benutzerdefinierten Shortcodes. Sie benötigt zwei Pflichtparameter: ein eindeutiges Tag und den Namen der Callback-Funktion, die den Inhalt zurückgibt.

Laut der WordPress-Dokumentation erhält der Callback drei Argumente in fester Reihenfolge:

• $attributes, ein Array der im Shortcode übergebenen Attribute
• $content, der Text zwischen dem öffnenden und dem schließenden Tag
• $tag, der Tag-Name, unter dem der Shortcode registriert ist

Ein einfaches Beispiel, ein Shortcode, der „Hello World!" ausgibt:

1
// Shortcode callback function
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello World!';
4
}
5
// Shortcode registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Der Code kommt in die functions.php Ihres Child-Themes oder über ein Code Snippets-Plugin. Danach gibt [hello-world] im Beitragseditor „Hello World!" aus.

Warum return und nicht echo

Beachten Sie das return innerhalb der Callback-Funktion. Verwenden Sie echo, erfolgt die Ausgabe, bevor WordPress den Rest der Seite aufbaut, „Hello World!" landet ganz oben und der umgebende Inhalt wird verschoben.

Die Regel ist einfach: **Ein Shortcode-Callback gibt einen Wert immer per ****return** zurück. Kein echo, print oder direkte HTML-Ausgabe außerhalb eines Puffers.

Der init-Hook ist erforderlich

Die WordPress.org-Entwickler empfehlen, die Shortcode-Registrierung an init zu hängen, statt add_shortcode() direkt im Rumpf der functions.php aufzurufen. Ohne init hat WordPress seine internen Mechanismen möglicherweise noch nicht vollständig initialisiert, und der Shortcode wird schlicht nicht ausgelöst.

Syntax und Parameter

Funktionssignatur:

1
add_shortcode( string $tag, callable $callback )

$tag, der Shortcode-Name (ohne Klammern). Registrieren zwei Plugins einen Shortcode mit demselben Tag, überschreibt der letzte den vorherigen. Um Konflikte zu vermeiden, fügen Sie ein eindeutiges Präfix hinzu: nicht [gallery], sondern [myplugin_gallery].

$callback, der Name der Funktion, die den Inhalt zurückgibt. Sie können einen String mit dem Funktionsnamen, eine anonyme Funktion oder eine Klassenmethode übergeben (indem Sie ein Array [ $object, 'method_name' ] übergeben).

So verwenden Sie Shortcodes im Editor

Im WordPress-Editor, Gutenberg oder Classic, wird ein Shortcode in eckigen Klammern eingefügt. Für unser Beispiel:

[hello-world]

Die vollständige Form mit schließendem Tag funktioniert ebenfalls:

[hello-world][/hello-world]

Die zweite Option ist erforderlich, wenn Inhalt zwischen den Tags übergeben wird (mehr dazu weiter unten).

So rufen Sie einen Shortcode in PHP auf

In Theme-Templates oder Plugins werden Shortcodes über do_shortcode() ausgeführt:

1
echo do_shortcode( '[hello-world]' );

Die Funktion nimmt einen String entgegen, der einen Shortcode enthält, und gibt das Ergebnis seiner Ausführung zurück. Das ist nützlich, wenn Sie die Shortcode-Ausgabe in PHP-Logik einbetten müssen, beispielsweise in header.php oder innerhalb einer Schleife.

Daten an einen Shortcode übergeben: zwei Wege

Weg 1: Inhalt zwischen den Tags

Schließen Sie die Daten zwischen dem öffnenden und dem schließenden Tag ein:

[hello-world]from John to Mary[/hello-world]

Der Callback erhält den String from John to Mary über den zweiten Parameter $content:

1
// Callback with content substitution between tags
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello ' . $content . ' World!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Ergebnis: „Hello from John to Mary World!".

Weg 2: Attribute

Übergeben Sie Parameter direkt im öffnenden Tag:

[hello-world from="John" to="Mary"][/hello-world]

In der Callback-Funktion stehen Attribute über den ersten Parameter $attributes zur Verfügung, ein assoziatives Array, dessen Schlüssel den Attributnamen entsprechen:

1
// Callback with reading shortcode attributes
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello from ' . $attributes['from'] . ' to ' . $attributes['to'] . '!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Ausgabe: „Hello from John to Mary!". Attribute eignen sich besser für strukturierte Daten (Preis, URL, ID), während sich Inhalt zwischen den Tags besser für beliebigen Text eignet.

In der Praxis sollten Sie bei Attributen sofort shortcode_atts() ergänzen, eine eingebaute WordPress-Funktion, die übergebene Attribute mit einem Array von Standardwerten zusammenführt. Ohne sie löst der Zugriff auf $attributes['from'] einen PHP-Hinweis aus, wenn der Benutzer das Attribut nicht angegeben hat. Mit shortcode_atts() erhalten Sie stets ein gefülltes Array: definierte Schlüssel mit Fallback-Werten, und unbekannte Attribute werden automatisch herausgefiltert.

Zwei einsatzbereite Shortcodes für WordPress

1. Automatisches aktuelles Jahr

Der Shortcode [current-year] fügt eigenständig das aktuelle Jahr ein, ohne dass das Datum im Footer jeden Januar aktualisiert werden muss:

1
// Callback: returns current year via date('Y')
2
function current_year_shortcode_callback( $attributes, $content, $tag ) {
3
    return date( 'Y' );
4
}
5
// Registration of shortcode [current-year]
6
function current_year_shortcode() {
7
    add_shortcode( 'current-year', 'current_year_shortcode_callback' );
8
}
9
add_action( 'init', 'current_year_shortcode' );

Platzieren Sie [current-year] im Footer oder Beitragstext, und das Jahr aktualisiert sich automatisch.

2. Liste registrierter Benutzer

Der Shortcode [users-list] gibt die Namen aller Seitenbenutzer als Aufzählungsliste aus. Nützlich auf einer „Team"-Seite oder in Admin-Berichten:

1
// Callback: gets all users and generates HTML list
2
function my_custom_users_list() {
3
    $users = get_users();
4
    $list_html = '<ul>';
5
    foreach ( $users as $user ) {
6
        $list_html .= '<li>' . $user->data->display_name . '</li>';
7
    }
8
    $list_html .= '</ul>';
9
    return $list_html;
10
}
11
// Registration of shortcode [users-list]
12
function register_my_users_list_shortcode() {
13
    add_shortcode( 'users-list', 'my_custom_users_list' );
14
}
15
add_action( 'init', 'register_my_users_list_shortcode' );

get_users() ohne Argumente gibt alle Benutzer zurück. Um die Abfrage nach Rolle einzuschränken, übergeben Sie ein Array: get_users( [ 'role' => 'editor' ] ). Der Code kommt in die functions.php des aktiven Themes oder in ein eigenes Plugin.

Video: Shortcodes in WordPress erstellen

Ein kurzes Video zum Thema, das eine Shortcode-Registrierung von Grund auf zeigt, vom Schreiben der Funktion bis zum Test im Editor:

⁉️🤔 Häufige Fragen

Was passiert, wenn zwei Plugins einen Shortcode mit demselben Tag registrieren?

WordPress führt denjenigen aus, der zuletzt geladen wurde. Der erste Shortcode wird stillschweigend überschrieben, ohne Fehlermeldung. Verwenden Sie deshalb immer ein Präfix in Ihren Shortcodes: [acme_gallery] statt [gallery]. Das schließt Konflikte mit jedem anderen Plugin oder Theme aus.

Können Shortcodes innerhalb anderer Shortcodes aufgerufen werden?

Ja. Wenn der Callback des ersten Shortcodes einen String zurückgibt, der das Tag des zweiten Shortcodes enthält, verarbeitet WordPress den verschachtelten Shortcode automatisch. Vergessen Sie aber do_shortcode() nicht: Wenn Sie Inhalte manuell zusammenbauen und diese Shortcodes enthalten, führen Sie den String explizit durch do_shortcode(). Das Standardverhalten von the_content erledigt das von selbst, ein direkter Callback-Aufruf hingegen nicht.

Wo sollte der Shortcode-Code leben, im Theme oder in einem Plugin?

Benutzerdefinierte Shortcodes transportieren Funktionalität, nicht Gestaltung, daher ist es besser, sie in ein separates Plugin auszulagern. Ein Theme-Wechsel legt die Seite dann nicht lahm: Die Shortcodes funktionieren weiter. Verwenden Sie mindestens ein Child-Theme, wenn Sie sicher sind, das übergeordnete Theme nicht zu wechseln.

Gibt es Einschränkungen beim Tag-Namen?

Der Name muss aus lateinischen Buchstaben, Ziffern und Bindestrichen bestehen. Leerzeichen, Unterstriche und Sonderzeichen sind nicht zulässig. Empfohlene Länge: bis zu 20 Zeichen, Kleinbuchstaben. Beispiel: [my-plugin-shortcode].

Wie debuggt man einen Shortcode, wenn er nichts ausgibt?

Erster Schritt: Aktivieren Sie WP_DEBUG in wp-config.php. Zweitens: Prüfen Sie, ob der Callback einen Wert per return zurückgibt, nicht per echo. Drittens: Stellen Sie sicher, dass der init-Hook vorhanden ist. Wenn keine Fehler auftreten, die Ausgabe aber leer bleibt, fügen Sie error_log() innerhalb des Callbacks ein und prüfen Sie die Server-Logs.

Was Sie sich zu WordPress-Shortcodes merken sollten

Shortcodes sind ein ausgereifter und stabiler Mechanismus. add_shortcode() hat sich seit Jahren nicht verändert: Tag, Callback, init-Hook, return statt echo. Merken Sie sich diese vier Dinge, und jeder benutzerdefinierte Shortcode funktioniert auf Anhieb.

• Wenn Sie das Jahr im Footer ausgeben, greifen Sie zum fertigen [current-year].
• Wenn Sie eine Benutzerliste benötigen, zu [users-list] mit Rollenfilter.
• Wenn Sie einen eigenen Shortcode von Grund auf schreiben, verwenden Sie immer ein Präfix und immer init.

Als nächsten Schritt sehen Sie sich an, wie Sie einen Shortcode als eigenständiges Plugin paketieren und im WordPress.org-Verzeichnis einreichen, das ist der beste Weg, Funktionalität vom Theme zu trennen und Ihr Entwicklerprofil aufzuwerten.