Ein Guide zu WordPress Shortcodes

Was ist ein Shortcode?

Ein Shortcode ist ein Platzhalter für eine in einem Theme oder Plugin definierte Funktion.

Wenn dieser Platzhalter im Inhalt eines Beitrags eingesetzt wird, dann führt er die im Quelltext hinterlegte Funktion aus. Meist ist die Funktion, im Frontend das gewünschte HTML auszugeben.

Ein Plugin, das einen Shortocde bietet, ist Shariff Wrapper. Shariff Wrapper ermöglichst es, Teilen-Buttons von sozialen Netzwerken in die eigene Seite zu integrieren.

Um die Teilen-Buttons in die eigene Seite zu integrieren, kannst du nach der Installation des Plugins an beliebiger Stelle im Inhalt shariff – umgeben von eckigen Klammern – hinterlegen. Der User wird im Frontend die Teilen-Buttons wie folgt sehen:

Vorteil von Shortcodes

Shortcodes verwalten Funktion und Inhalt zentral im Quelltext. Mit Shortcodes können wiederkehrend verwendete Elemente somit an einer Stelle angepasst werden. Die Darstellung der Elemente ändert sich dabei seitenweit.

Globale, seitenweite Änderungen wiederkehrender Elemente können in der Regel schnell und einfach mit Shortcodes realisiert werden.

Anwendungsbeispiele:

• Ein neues Netzwerk zu den Social-Media-Teilen-Buttons hinzufügen. Einmal den Shortcode bearbeiten, seitenweit das neue Netzwerk anzeigen.
• Ein Werbebanner für die Aktion der Woche, der inmitten von Bloginhalten angezeigt wird. Wenn sich die Aktion ändert, kann an einer Stelle angepasst werden und alle bestehenden Seiten zeigen die aktuelle Aktion.
• Logoreihe von zufriedenen Kunden. Wenn neue Kunden hinzukommen, kann die Darstellung der Logo-Reihe an einer Stelle zentral verwaltet werden. Änderungen werden seitenweit angezeigt.

Weitere Vorteile

• Shortcodes lassen sich einfacher in einen Beitrag integrieren, als individuelles HTML und CSS.
• Shortcodes sind in der regel sicherer für Redakteure zu verwenden, als individuelles HTML, CSS und JavaScript.
• Shortcodes können einfach über ein Funktionalitäts-Plugin in mehrere deiner Seite integriert werden, sofern nötig. so kannst du deine Funktionen einfach und schnell auf mehreren Seiten verfügbar machen.
• Shortcodes sind einfach zu entwickeln – im Vergleich zu dem Setup und dem Wissen, das es benötigt, um einen WordPress Block für Gutenberg zu entwickeln.

Arten und Anwendung von Shortcodes

Shortcodes können verschiedene Level an Komplexität abdecken.

Hier einige Beispiele mit ausgedachten Shortcodes.

[galerie]

• Dieser Shortcode zeigt eine Fotogalerie mit allen Fotos aus der Mediathek.

[galerie titel="Urlaub in Island" fotos="8,32,15"]

• Dieser Shortcode zeigt eine Fotogalerie mit vom Redakteur festgelegten Fotos. Angezeigt werden die Fotos mit den IDs 8, 32 und 15.
• Über der Galerie wird die Überschrift „Urlaub in Island“ angezeigt.

Das tolle ist hierbei, dass die Fotogalerie beliebig auf der Seite eingesetzt werden kann und gleichzeitig flexibel bleibt. Redakteure können ohne Programmierkenntnisse Einfluss auf den Inhalt nehmen.

[produktempfehlungen titel="Passend für den nächsten Urlaub in Island"]
  [produkt id="5" hinweis="Extra leichtes Material"]
  [produkt id="21" hinweis="10 Stunden Akkulaufzeit"]
[/produktempfehlungen]

• Der Shortcode produktempfehlungen zeigt einen Abschnitt mit Produktempfehlungen. Der Abschnitt beginnt mit einer Überschrift, gefolgt von definierten Produkten.
• Produkte werden innerhalb der Empfehlung über ihre ID mit einem eigenen Shortcode produkt definiert. Produkte können zudem einen optionalen Hinweis anzeigen.

Es gibt also

• einfache Shortcodes, die einen festen Inhalt ausgeben
• Shortcodes deren Inhalte mit Attributen gesteuert werden
• und Shortcodes, deren Inhalt frei definiert wird. Beispielsweise, in dem weitere Shortcodes oder individuelles HTML eingebracht wird.

Wie kann ich einen Shortcode in den Inhalt einfügen?

• Classic-Editor: Packe deinen Shortcode einfach in den Inhaltsbereich. An die Stelle, an der er angezeigt werden soll.
• Gutenberg-Editor: Verwende den Block „Shortcode“ und packe deinen Shortcode in den Block. Du kannst Shortocdes auch einfach im Fließtext anwenden. Der Shortcode-Block ist kein Muss.
• Template-Dateien: Shortcodes können via do_shortcode-Funktion (engl.) direkt in PHP-Dateien ausgeführt werden.

Tipps für die Verwendung von Shortcodes im Team

Bei der exzessiven Nutzung von Shortcodes geht schnell die Übersichtlichkeit verloren, weil für Redakteure in der Regel nicht erkennbar ist, welche Shortcodes es auf der Seite gibt und wie sie zu verwenden sind.

Hier ein paar Tipps, um Shortcodes sinnvoll für die Teamarbeit verfügbar zu machen und Arbeitsabläufe zu vereinfachen.

• Dokumentiere, beispielsweise in einem internen Dokument oder eine Info-Seite im Backend der WordPress-Seite, welche Shortcodes seitenweit zu Verfügung stehen, wie diese genutzt werden können und wie das erwartete Ergebnis im Frontend aussieht, wenn das Element richtig verwendet wird.
• Stelle eigene Shortcodes bereit, die beispielsweise von Themes und Plugins genutzte Shortcodes umschließen. So kannst du Funktionen und Inhalte beim Wechsel von Themes und Plugins migrieren ohne jeden veröffentlichten Inhalt manuell aktualisieren zu müssen. Du musst nur deine Shortcode-Funktionen aktualisieren, wenn sich etwas in einem installierten Theme oder Plugin ändert.

Einen eigenen Shortcode erstellen

Um einen eigenen Shortcode zu erstellen, nutze ich gerne ein eigenes Plugin, dass die Eigenheiten und Erweiterungen meiner Seite beinhaltet.

Wenn du noch kein eigenes Plugin für Funktionsanpassungen hast, kannst du deinen ersten Shortcode beispielsweise in einer PHP-Datei deines Child-Themes erstellen und hinterlegen.

Im folgenden Beispiel einen Shortcode, der den Inhalt von einem externen Social-Media-Plugin-Shortcode mit einen div umschließt und ausgibt.

Wenn ich später ein anderes Social-Plugin nutzen will, kann ich in meinem eigenen Shortcode-Quelltext das shariff in do_shortcode gegen den Shortcode-Namen des neuen Plugins austauschen. Meine Seite zeigt die Inhalte des neuen Plugins an, ohne dass ich alle Beiträge bearbeiten muss, in dem die Teilen-Buttons verwendet werden.

function webfluence_social_shortcode() {
  ob_start();?>
  <div class="webfluence-social-section">
  <?php echo do_shortcode('[shariff]'); ?>
  </div>

  <?php
  $shortcode_content = ob_get_contents();
  ob_end_clean();
  return $shortcode_content;
}

add_shortcode('wf-social', 'webfluence_social_shortcode' );

Referenz: add_shortcode (engl)

Code-Erklärung:

• add_shortcode('wf-social', 'webfluence_social_shortcode' ); definiert den Shortcode wf-social. Der Inhalt wird von der Funktion webfluence_social_shortcode generiert und ausgegeben.
• Die Funktion webfluence_social_shortcode ist eine einfache PHP-Funktion, die einen Inhalt für den Shortcode generiert und ausgibt.
  • Was in der Funktion passiert, ist uns selbst überlassen. Wichtig ist, dass das Ergebnis mit einem return zurückgegeben wird.
  • Der Name der Funktion darf frei gewählt werden.

So kann der Shortcode eingesetzt werden:

[wf-social]

Der in diesem Beispiel erstellte Shortcode akzeptiert keine Parameter. Er wird einfach in den Inhalt eines Beitrags eingesetzt.

Attribute an einen Shortcode übergeben

Wenn wir erlauben wollen, dass der Shortcode Attribute entgegennimmt, dann können wir die Shortcode-Funktion anpassen und Zugriff auf die vom User eingegebenen Inhalte ermöglichen.

function webfluence_social_shortcode($atts=array()) {
  $atts = shortcode_atts(
    array(
      'class' => '',
    ), $atts, 'wf-social' );

  $css_class = $atts['class'];

  ob_start();?>
  <div class="<?php echo esc_attr('webfluence-social-section ' . $css_class); ?>">
  ...
  return $shortcode_content;
}

Die Attribute ($atts) werden als array übergeben. Darum erfolgt der Zugriff ein Attribut über die Schreibweise mit den eckigen Klammern.

Der Shortcode erlaubt Redakteuren das hinzufügen eigener CSS-Klassen über folgende Schreibweise:

[wf-social class="has-yellow-background-color"]

Ausgegeben wird im Frontend:

 <div class="webfluence-social-section has-yellow-background-color">
...

Inhalte an einen Shortcode übermitteln

Wenn der Shortcode nun auch Inhalte zwischen der eigenen, öffnenden und schließenden Tags erlauben soll, dann wird die Funktion um das Argument $content erweitert.

Wichtig ist, dass das $content-Argument nach $atts kommt. Auch wenn der User keine Attribute ausfüllt, wird der Content erst an zweiter Stelle an die Funktion übermittelt.

function webfluence_social_shortcode($atts=array(), $content = "") {
  $atts = shortcode_atts(
    array(
      'class' => '',
    ), $atts, 'wf-social' );

  $css_class = $atts['class'];

  ob_start();?>
  <div class="<?php echo esc_attr('webfluence-social-section ' . $css_class); ?>">
  <?php echo $content; ?>
  ...
  return $shortcode_content;
}

Der Shortcode kann nun mit öffnenden und schließenden Tags verwendet werden.

[wf-social class="has-yellow-background-color"]<p>Hier bin ich</p>[/wf-social]

Ausgegeben wird im Frontend:

<div class="webfluence-social-section has-yellow-background-color">
<p>Hier bin ich</p>
...

Shortcodes modifizieren (Output filtern)

Besonders spannend wird es, wenn Inhalte über Shortcodes von Plugins Dritter in die eigene Seite integriert werden und diese angepasst werden sollen.

Beispielsweise stand einer meiner Kunden vor der Herausforderung, die im eigenen WooCommerce-Shop angezeigten Produkt- und Größentabellen zu übersetzen. Hochgeladen werden die Tabellen in deutsch. Für die englische Shopseite ist eine Übersetzung nötig.

Normalerweise würde ein Redakteur nun alle Tabellen, die auf der Seite sind, händisch übersetzen. Das würde ewig dauern und wäre ziemlich repetitiv.

Wir haben uns dazu entschieden, die Tabellen in deutscher Sprache mit TablePress anzulegen und über den mitgelieferten table-Shortcode an den benötigten Stellen in die Seite zu integrieren.

Um die Inhalte nicht manuell übersetzen zu müssen, wird der Shortcode-Inhalt einer TablePress-Tabelle über eine eigene Funktion vor der Ausgabe manipuliert, sofern die angezeigte Sprache nicht deutsch ist.

Hier ein vereinfachter Auszug des Codes:

/**
 * @param string $output The output from the shortcode
 * @param string $tag The name of the shortcode
 *
 * @return string The modified output
 */
function webfluence_translate_tablepress_shortcode_content( $output, $tag ) {
  $lang = apply_filters( 'wpml_current_language', NULL );
  if ( $tag !== 'table' || $lang === 'de')
    return $output;

  $array = [
    'In Entwicklung' => 'under development',
    'K.A.' => 'unknown ',
    'Support kontaktieren' => 'contact support'
  ];
  foreach( $array as $key => $value )
    // str_ireplace = insensitive - upper/lowercase
    $output = str_ireplace($key, $value, $output);
  }
  return $output;		  
}

add_filter('do_shortcode_tag', 'webfluence_translate_tablepress_shortcode_content', 10, 2);

Referenz: do_shortcode_tag (engl.)

Code-Erklärung:

1. Es wird die Sprache abgefragt, die der User ansieht.
   • Wenn die Sprache nicht „deutsch“ ist und der table-Shortcode durchlaufen wird, geht es weiter.
   • Andernfalls wird der bestehende Shortcode-Inhalt direkt zurückgegeben.
2. Nun wird eine Liste mit den zu übersetzenden Inhalten bereitgestellt.
   • key ist immer der deutsche, zu ersetzende Ausgangstext, der bereits in den Tabellen verwendet wird.
   • value ist der englische Text, also der Zielwert, der angezeigt werden soll, wenn die Sprache nicht deutsch ist.
3. Anschließend wird die Liste mit den Übersetzungsinhalten über eine foreach-Schleife durchlaufen.
   • Der bestehende Shortcode-Inhalt wird genommen und der deutsche Wert ($key) gegen den englischen Zielwert ($value) ausgetauscht.
4. Abschließend wird der Shortcode-Inhalt mit den übersetzten Inhalten zurückgegeben.

Dank dieser Lösung können nun alle Produkttabellen – die die Firma derzeit noch in Excel pflegt – einfach via TablePress in die Seite reingeladen werden.

Das System übersetzt die fest definierten Werte vor der Ausgabe im Frontend automatisch von deutsch nach englisch. Das spart einiges an Zeit.