⚡ So fügen Sie Ihren eigenen Shortcode in WordPress hinzu: Beispiele und Code

Sie müssen das Datum der letzten Aktualisierung eines Beitrags im Footer jedes Artikels ausgeben. Oder ein Abonnementformular exakt in der Mitte des Textes einfügen, ohne Code-Editor und Template-Akrobatik. In WordPress sind Shortcodes das Werkzeug dafür.

Ein Shortcode ist ein kurzer Tag in eckigen Klammern: [myshortcode]. WordPress findet ihn im Inhalt und ersetzt ihn durch das Ergebnis einer PHP-Funktion. Sie verwenden Standard-Shortcodes wie [gallery] und [embed] ständig, ohne darüber nachzudenken. Ihr eigener Shortcode hingegen ist ein Hebel: Sie schreiben die Logik einmal, und der Redakteur fügt ihn mit drei Klicks überall ein.

In 10 Minuten erstellen Sie Ihren ersten funktionierenden Shortcode: von einer leeren Funktion bis zu einem Tag mit Attributen und umschlossenem Inhalt. Der Code ist echt, läuft auf jedem modernen WordPress und wurde auf einer Staging-Site getestet.

💡 Kurzüberblick:

• Die Funktion add_shortcode: was sie entgegennimmt und wie sie intern arbeitet
• Ein einfacher [current_year]-Shortcode, das aktuelle Jahr als Text
• Ein Shortcode mit Attributen [cta text="Скачать"], ein individueller Button
• Ein Shortcode mit umschlossenem Inhalt [notice]Текст[/notice], ein gestalteter Block
• Einbindung per Plugin oder functions.php: Vor- und Nachteile beider Wege
• Häufige Fehler: echo statt return, Namenskonflikte, leeres Attribut in PHP 8+

Was add_shortcode leistet und wie es funktioniert

Die Funktion add_shortcode ist der einzige standardisierte Weg, einen neuen Shortcode in WordPress zu registrieren. Sie akzeptiert zwei Parameter:

• $tag (String), der Shortcode-Name, den Sie in eckige Klammern schreiben. Nur Buchstaben, Zahlen und Unterstriche. Leerzeichen und Sonderzeichen & / < > [ ] = sind nicht erlaubt; WordPress verweigert die Registrierung eines solchen Tags stillschweigend.
• $callback (Callable), der Name der PHP-Funktion, die ausgeführt wird, wenn der Shortcode gefunden wird. Diese Funktion generiert das HTML, das der Besucher sieht.

Der Quellcode der Funktion, fünf Zeilen Logik und zwei Plausibilitätsprüfungen (vollständige Auflistung auf developer.wordpress.org):

1
function add_shortcode( $tag, $callback ) {
2
    global $shortcode_tags;
3
 
4
    if ( '' === trim( $tag ) ) {
5
        _doing_it_wrong(
6
            __FUNCTION__,
7
            __( 'Invalid shortcode name: Empty name given.' ),
8
            '4.4.0'
9
        );
10
        return;
11
    }
12
 
13
    if ( 0 !== preg_match( '@[<>&/\[\]\x00-\x20=]@', $tag ) ) {
14
        _doing_it_wrong(
15
            __FUNCTION__,
16
            sprintf(
17
                /* translators: 1: Shortcode name, 2: Space-separated list of reserved characters. */
18
                __( 'Invalid shortcode name: %1$s. Do not use spaces or reserved characters: %2$s' ),
19
                $tag,
20
                '& / < > [ ] ='
21
            ),
22
            '4.4.0'
23
        );
24
        return;
25
    }
26
 
27
    $shortcode_tags[ $tag ] = $callback;
28
}

Der entscheidende Punkt: $shortcode_tags, ein globales Array. WordPress speichert darin alle registrierten Shortcodes. Während der Inhaltsausgabe iteriert der Kern über dieses Array und ruft für jeden gefundenen Tag die zugehörige Funktion auf. Daraus ergeben sich zwei Konsequenzen:

• *Registrieren Sie am init-Hook.* Wenn Sie add_shortcode direkt in einer Plugin-Datei aufrufen, kann das geschehen, bevor WordPress vollständig initialisiert ist. Der korrekte Weg ist, den Aufruf in einen Hook zu verpacken:

1
add_action( 'init', 'my_register_shortcodes' );
2
 
3
function my_register_shortcodes() {
4
    add_shortcode( 'mytag', 'my_shortcode_callback' );
5
}

• Ein Präfix ist obligatorisch. Das globale Array wird von allen Plugins und dem Theme gemeinsam genutzt. Nennen Sie einen Shortcode [button], überschreibt Ihr [button] stillschweigend denselben Shortcode eines Formular-Plugins. Ein Präfix wie myplugin_ oder ein eindeutiges Kürzel löst das Problem. In den folgenden Beispielen verwende ich das Präfix mysite_; in einem realen Projekt ersetzen Sie es durch Ihr eigenes.

Schritt 1: ein einfacher Shortcode ohne Parameter

Der kürzeste Weg zu einem funktionierenden Shortcode, drei Zeilen in der functions.php Ihres Child-Themes (oder im Code Snippets-Plugin, was sicherer ist und bei einem Theme-Update nicht verloren geht).

Fügen Sie diesen Code ein und speichern Sie:

1
add_shortcode( 'mysite_current_year', 'mysite_display_current_year' );
2
 
3
function mysite_display_current_year() {
4
    return date( 'Y' );
5
}

Schreiben Sie nun [mysite_current_year] in einen beliebigen Beitrag oder eine Seite. Im Frontend erscheint anstelle des Shortcodes das aktuelle Jahr: "2026".

Was hier passiert. Die Funktion mysite_display_current_year nimmt keine Argumente entgegen, ruft die PHP-Funktion date('Y') auf und gibt eine vierstellige Zeichenkette zurück. WordPress fügt diese Zeichenkette exakt an der Stelle ein, an der der Shortcode platziert wurde. Keine Magie.

Wo Sie dies in der Praxis anwenden: die Jahreszahl im Footer (© [mysite_current_year]), das Projektalter im Text („seit [mysite_current_year] tätig"), die automatische Aktualisierung von Datumsangaben auf Seiten zur rechtlichen Compliance.

Schritt 2: ein Shortcode mit Attributen

Ein Shortcode ohne Parameter ist nützlich, aber die wirkliche Flexibilität beginnt mit Attributen. Das klassische Beispiel, ein Button mit anpassbarem Text und einem Link:

1
add_shortcode( 'mysite_cta', 'mysite_cta_button' );
2
 
3
function mysite_cta_button( $atts ) {
4
    $atts = shortcode_atts(
5
        array(
6
            'text' => 'Learn more',
7
            'url'  => '#',
8
        ),
9
        $atts,
10
        'mysite_cta'
11
    );
12
 
13
    return sprintf(
14
        '<a href="%s" class="mysite-cta-button">%s</a>',
15
        esc_url( $atts['url'] ),
16
        esc_html( $atts['text'] )
17
    );
18
}

Im Editor verwenden Sie ihn so:

1
[mysite_cta text="Download plugin" url="https://example.com/myplugin/"]

Die Funktion shortcode_atts erledigt drei Dinge auf einmal: Sie führt Benutzerattribute mit Standardwerten zusammen, filtert nur bekannte Schlüssel und normalisiert einen leeren String zu einem Array (ohne dies würde der Aufruf von [mysite_cta] ohne Attribute in PHP 8+ einen TypeError auslösen, weil der erste Parameter der Callback-Funktion einen leeren String anstelle eines Arrays erhielte).

*Warum esc_url und esc_html.* Ein Shortcode wird von einem Redakteur eingefügt, heute sind das Sie, und morgen ein Content Manager ohne Code-Zugriff. Die Ausgabe-Escapierung schützt vor versehentlichem XSS, falls eine Klammer oder ein Tag im Attribut text landet.

Schritt 3: ein Shortcode mit umschlossenem Inhalt

Manche Shortcodes umschließen ein Textfragment: [mysite_notice]Важное сообщение[/mysite_notice]. Der umschlossene Inhalt erreicht den Callback als zweiten Parameter, $content. Ein typisches Szenario, ein gestalteter Warnhinweis:

1
add_shortcode( 'mysite_notice', 'mysite_notice_box' );
2
 
3
function mysite_notice_box( $atts, $content = null ) {
4
    $atts = shortcode_atts(
5
        array(
6
            'type' => 'info',
7
        ),
8
        $atts,
9
        'mysite_notice'
10
    );
11
 
12
    $class = 'notice-' . esc_attr( $atts['type'] );
13
 
14
    return sprintf(
15
        '<div class="mysite-notice %s"><p>%s</p></div>',
16
        $class,
17
        do_shortcode( $content )
18
    );
19
}

Beachten Sie do_shortcode( $content ). Wenn der Redakteur einen weiteren Shortcode in Ihren Shortcode eingefügt hat (zum Beispiel [mysite_current_year]), führt dieser Wrapper ihn ebenfalls aus. Ohne do_shortcode werden verschachtelte Shortcodes als Text in eckigen Klammern angezeigt, roh [mysite_current_year] anstelle von „2026".

CSS für den Block, minimal, für den Einstieg:

1
.mysite-notice {
2
    border-left: 4px solid #2271b1;
3
    background: #f0f6fc;
4
    padding: 1em 1.2em;
5
    margin: 1.5em 0;
6
    border-radius: 4px;
7
}
8
.mysite-notice.notice-warning {
9
    border-left-color: #dba617;
10
    background: #fcf9e8;
11
}

Fügen Sie die Stile der style.css Ihres Child-Themes hinzu oder über Design → Customizer → Zusätzliches CSS.

Schritt 4: ein Shortcode innerhalb eines Plugins (OOP-Ansatz)

Wenn Sie mehr als drei Shortcodes haben, wird functions.php zur Abladefläche. Es ist an der Zeit, die Logik in ein separates Plugin auszulagern, idealerweise in eine Klasse. Hier ist ein Mini-Plugin-Gerüst mit einem Shortcode:

1
<?php
2
/**
3
 * Plugin Name:  MySite Shortcodes
4
 * Description:  Custom shortcodes for the site.
5
 * Version:      1.0.0
6
 * Requires PHP: 7.4
7
 */
8
 
9
defined( 'ABSPATH' ) || exit;
10
 
11
class MySite_Shortcodes {
12
 
13
    public static function init() {
14
        add_action( 'init', array( __CLASS__, 'register' ) );
15
    }
16
 
17
    public static function register() {
18
        add_shortcode( 'mysite_email', array( __CLASS__, 'email_obfuscated' ) );
19
    }
20
 
21
    public static function email_obfuscated( $atts ) {
22
        $atts = shortcode_atts(
23
            array( 'address' => '' ),
24
            $atts,
25
            'mysite_email'
26
        );
27
 
28
        if ( ! is_email( $atts['address'] ) ) {
29
            return '';
30
        }
31
 
32
        return sprintf(
33
            '<a href="mailto:%1$s">%1$s</a>',
34
            antispambot( $atts['address'], 1 )
35
        );
36
    }
37
}
38
 
39
MySite_Shortcodes::init();

Platzieren Sie diese Datei in wp-content/plugins/mysite-shortcodes/mysite-shortcodes.php und aktivieren Sie das Plugin im Admin-Bereich. Der Shortcode [mysite_email address="hello@example.com"] gibt einen vor Spam-Bots geschützten Link aus; die Funktion antispambot kodiert E-Mail-Zeichen in HTML-Entitäten.

Warum eine Klasse, nicht eine Sammlung von Funktionen. Namespacing: Drei Shortcodes in einer Klasse kollidieren nicht mit Funktionen von Drittanbietern. Plus Autoloading, plus lesbarer Code, wenn das Plugin auf ein Dutzend Shortcodes anwächst.

Testen eines Shortcodes vor der Veröffentlichung

Prüfen Sie nach dem Hinzufügen des Codes drei Szenarien:

• Shortcode ohne Attribute. Nur [mysite_cta], er sollte mit Standardwerten rendern (Text „Learn more", Link #).
• Shortcode mit Attributen. Ein vollständiger Satz von Parametern, alle Werte werden übernommen und korrekt angezeigt.
• Fehler in Attributen. Eine ungültige E-Mail in [mysite_email], die Funktion gibt still einen leeren String zurück, anstatt die Seite zu zerstören.

Wichtig: Verwenden Sie niemals echo innerhalb einer Callback-Funktion. Ein Shortcode muss einen String via return zurückgeben. Wenn Sie HTML mit echo ausgeben, erscheint es nicht dort, wo der Shortcode steht, sondern ganz oben auf der Seite, weil WordPress das Shortcode-Rendering vor der Inhaltsausgabe ausführt. Dieselbe Logik wie bei Filtern: Die Funktion reicht einen Wert zurück, und die Engine selbst entscheidet, wo sie ihn einfügt.

Eine zweite Nuance: Wenn der Shortcode nicht angezeigt wird (Sie sehen [mysite_cta] als Text, nicht als Button), prüfen Sie, ob die Funktion am init-Hook registriert ist und nicht direkt im Plugin-Body. Ohne init ist das globale Array $shortcode_tags möglicherweise noch nicht bereit, neue Tags anzunehmen.

Shortcode im Theme vs. in einem Plugin: Was ist zu wählen

Die Regel: Beginnen Sie mit functions.php auf einer Testseite, bauen Sie drei Shortcodes und verlagern Sie sie dann in ein Plugin. Ein Theme-Update sechs Monate später wird Ihre Logik nicht begraben, und Sie können die Shortcodes in einer Minute in ein anderes Projekt übertragen.

⁉️🤔 FAQ

Was ist der Unterschied zwischen einem Shortcode und einem Gutenberg-Block?

Ein Shortcode ist ein Text-Tag in eckigen Klammern, das serverseitig verarbeitet wird. Ein Block ist eine visuelle Editor-Komponente, eine React-Komponente mit Einstellungen in der Seitenleiste. Shortcodes kamen mit WordPress 2.5 (2008), Blöcke mit 5.0 (2018). Heute sind Blöcke der primäre Weg, um dynamische Inhalte einzufügen, aber Shortcodes bleiben relevant: Sie sind einfacher zu entwickeln, erfordern keine JavaScript-Kenntnisse und funktionieren in jedem Editor, einschließlich des Classic Editors und von Page Buildern.

Ein Shortcode ist ein Text-Tag, das WordPress beim Rendern der Seite durch das Ergebnis einer PHP-Funktion ersetzt. Anders als ein Gutenberg-Block hat ein Shortcode keine visuelle Oberfläche im Editor: Der Content-Manager schreibt [myshortcode] als Text und sieht das fertige HTML erst im Frontend.

Kann ich einen Shortcode innerhalb eines anderen Shortcodes verwenden?

Ja. Wenn die Callback-Funktion des äußeren Shortcodes den verschachtelten Inhalt mit do_shortcode() umschließt, funktionieren die inneren Shortcodes korrekt: [notice][current_year][/notice] gibt einen gestalteten Block mit dem aktuellen Jahr aus. Ohne do_shortcode() bleibt der verschachtelte Shortcode als Text in eckigen Klammern stehen.

Verschachtelte Shortcodes werden rekursiv verarbeitet: WordPress durchläuft den String mehrfach, bis keine unverarbeiteten Tags mehr übrig sind. Damit das funktioniert, muss der äußere Shortcode jedoch explizit do_shortcode($content) aufrufen. Andernfalls bleibt der String [current_year] als Text stehen, anstatt zu "2026" zu werden.

Warum funktioniert mein Shortcode nicht und wird als Text in eckigen Klammern angezeigt?

Drei häufige Gründe. Erstens: add_shortcode wird vor dem init-Hook aufgerufen, verlagern Sie die Registrierung in add_action('init', ...). Zweitens: ein Tippfehler im Tag-Namen, [my_shortcode] im Editor, aber myshortcode ist registriert. Drittens: die Callback-Funktion verwendet echo statt return, sodass die Ausgabe oben auf der Seite landet und die Shortcode-Position leer bleibt.

Der häufigste Übeltäter ist echo statt return in der Callback-Funktion. WordPress ruft Shortcode-Handler auf, bevor der Hauptinhalt ausgegeben wird, daher landet das Ergebnis von echo früher im Ausgabepuffer als der Seitenkopf. Öffnen Sie den Seitenquelltext (Strg+U): Wenn Sie das HTML des Shortcodes ganz oben sehen, vor <html>, ist genau das das Problem.

Muss ich die Shortcode-Ausgabe escapen?

Unbedingt. Ein Shortcode akzeptiert Attribute aus dem Editor, also potenziell von jedem Benutzer mit Autoren- oder Redakteursrechten. esc_html() für Text, esc_url() für Links, esc_attr() für HTML-Attribute. Die Ausnahme ist, wenn Sie absichtlich HTML-Markup zurückgeben (wie <div class="notice">). Aber auch dann escapen Sie Attribute innerhalb des Markups.

Ja, Escaping ist Pflicht für alles, was aus Shortcode-Attributen oder Benutzereingaben stammt. Auch wenn heute nur Sie Shortcodes einfügen, bekommt morgen ein Content-Manager Redakteurszugang. esc_html() für Text, esc_url() für Links, esc_attr() für HTML-Attribute schützen vor versehentlichem oder absichtlichem XSS.

Wie viele Shortcodes kann ich auf einer Site registrieren?

Es gibt kein technisches Limit: $shortcode_tags ist ein normales PHP-Array, Sie erreichen das Server-Speicherlimit weit später als den gesunden Menschenverstand. In der Praxis lohnt sich nach 15-20 eigenen Shortcodes die Frage: Ist es an der Zeit, einige davon in Gutenberg-Blöcke zu überführen? Behalten Sie Shortcodes mit eindeutiger Logik (E-Mail-Verschleierung, bedingte Ausgabe nach Rolle). Für Shortcodes, die nur Text stylen ([highlight]), ist es besser, einen Block-Stil oder eine CSS-Klasse zu verwenden.

Technisch gesehen so viele, wie Sie möchten: Das $shortcode_tags-Array hat kein künstliches Limit. Praktisch deutet mehr als 20-25 Shortcodes auf einer Site darauf hin, dass ein Teil der Logik in Blöcke verlagert werden sollte. Jeder Shortcode verursacht Overhead beim Parsen des Inhalts: Vor der Ausgabe iteriert WordPress über das gesamte Array registrierter Tags und sucht im Beitragstext nach Übereinstimmungen.

Sollte ich eigene Shortcodes schreiben oder reichen fertige Plugins?

Ein fertiges Plugin deckt die meisten typischen Aufgaben ab: Formulare, Contact Form 7, Tabellen, TablePress, Raster, jeder Page Builder. Ein eigener Shortcode ist nötig, wenn die Logik spezifisch für Ihre Site ist und keine fertige Lösung existiert: Ausgabe eines benutzerdefinierten Feldes genau an dieser Stelle der Seite, das Datum des nächsten Webinars aus der Datenbank, eine personalisierte Begrüßung basierend auf der Benutzerrolle.

Kurz gesagt: Für Standardfunktionalität nutzen Sie ein Plugin und programmieren nicht. Für einzigartige Logik: add_shortcode + functions.php oder ein Mini-Plugin. Der Code in jedem der obigen Beispiele umfasst weniger als zehn Zeilen. Sobald Sie diese drei Muster beherrschen (einfach, mit Attributen, mit verschachteltem Inhalt), decken Sie die große Mehrheit der Aufgaben ab, für die überhaupt eigene Shortcodes geschrieben werden.