Shortcodes überschreiben

Theme gekauft, Plugins installiert und schon sind die neuen Shortcodes da. Leider funktionieren manche nicht wie der Kunde es sich wünscht. Um sie anzupassen bietet WordPress 4.7 einen neuen tollen Weg.

Der „pre_do_shortcode_tag“-Filter

Mit WordPress 4.7 kam der „pre_do_shortcode_tag“-Filter rein. Dieser wird vor jedem, wirklich jedem Shortcode aufgerufen und erlaubt, einen Shortcode on-the-fly zu überschreiben. Im Code von WordPress heißt es:

Filters whether to call a shortcode callback.
Passing a truthy value to the filter will effectively short-circuit the shortcode generation process, returning that value instead.

Dieser „short-circuit“ (oft auch „early exit“ genannt) bietet also Filter-Funktionen auf, eine Rückgabe zu erzeugen, welche dem Wahrheitswert „true“ entspricht. Das kann alles von einer großen Zahl bis zu einem ganzen HTML-String sein. Selbst ein String mit einem Leerzeichen gilt und würde einen Shortcode „abschalten“. Was das genau heißt und wie es eingesetzt werden kann, möchte ich im Folgenden zeigen.

Shortcodes je Kontext ändern

Das Tolle an diesem Filter ist, dass er je nach Kontext Shortcodes unterdrücken könnte oder diese einfach anders aussehen. Nehmen wir zum Beispiel einen „[user_profile]“ Shortcode, welcher üblicherweise ein Formular zum Ändern des eigenen Profils anbietet. Diese Funktion  ist fix in ein Plugin oder Theme gegossen und soll um eine Anforderung erweitert werden. Der Benutzer darf erst seine Sachen bearbeiten, wenn er freigeschaltet worden ist. Super einfach!

add_filter(
  'pre_do_shortcode_tag',
  function ( $ausgabe, $shortcode ) {

    if ( 'user_profile' !== $shortcode ) {
      // nicht der "user_profile" shortcode => ignorieren
      return $ausgabe;
    }

    if ( get_user_meta( get_current_user_id(), 'aktiviert', true ) ) {
      // Benutzer ist aktiv => Shortcode machen lassen
      return $ausgabe;
    }

    // Es bleibt über: Richtiger Shortcode & Benutzer nicht freigeschaltet
    return 'Sie sind noch nicht freigeschaltet!';

  },
  10,
  2
}

Das ist fast schon mehr Dokumentation als Code. Erst wird geprüft, ob der Filter überhaupt für den gewünschten Shortcode aufgerufen wurde. Ist dies nicht der Fall, dann wird die Eingabe direkt wieder zurückgeschickt.
Soll doch der Shortcode „[user_profile]“ gefiltert werden, dann kommt die nächste Hürde. Es wird geprüft, ob der Benutzer bereits freigeschaltet wurde. Ist das der Fall, dann endet die Funktion ebenfalls wieder und lässt die Ausgabe unverändert vom Original zusammenstellen.
Ein Fall bleibt nun noch übrig: Es ist der Shortcode „user_profile“ aber der Benutzer ist bisher nicht freigeschaltet. Dann stellt die Funktion eine Ausgabe zusammen und übergibt diese im letzten return an WordPress. Dieses hebelt die eigentliche Implementierung vom Shortcode aus und anstelle des Formulars nur den obigen Einzeiler aus.

Nichts Neues, das geht besser

Shortcodes aushebeln ist keine neue Trickserei in WordPress. Es kann natürlich ein Shortcode deaktiviert werden und mit einem Wrapper drum herum wieder aktiviert werden. Hier ist das Problem allerdings, dass der richtige Zeitpunkt abgefangen werden muss. Mit dem neuen Filter kann der Entwickler schon sorgenfreier umgehen.

Die Sahnehaube wäre an dieser Stelle ein dynamischer Filter wie „pre_do_shortcode_{$tag}“, welcher je nach Shortcode aufgerufen wird. Dann bleibt sogar die Unterscheidung, ob aktuell der richtige Shortcode gefordert wird, erspart. Gleichzeitig ist es damit etwas aufgeräumter und vielleicht auch performanter. Bis dahin ist er auf jeden Fall ein schöner Filter, um mal eben Shortcodes umzuschreiben und an besondere Anforderungen zu adaptieren.