Neue Theme URL und Theme Pfad Funktionen in WordPress 4.7

Mit WordPress 4.7 hat der Core vier neue Funktionen für die Rückgabe von Theme URL bzw. Theme Pfad erhalten, welche die alten Funktionen ergänzen und teilweise ersetzen. In diesem Beitrag stelle ich die neuen Möglichkeiten vor.

Zum besseren Verständnis empfehle ich meinen Beitrag von letzter Woche zu lesen, in dem ich die bisherigen URL und Dateipfad Funktionen für Theme Entwickler vorgestellt habe.

Das Problem der altbekannten Funktionen ist, dass je nach Funktion entweder URL/Pfad des Parent Themes oder des Child Themes zurückgegeben wurde. Damit war es nicht möglich, Dateien in einem Child Theme zu überschreiben, wie es beispielsweise bei Template Dateien und get_template_part() möglich ist.

Aus diesem Grund wurden mit WordPress 4.7 neue Funktionen eingeführt.

get_theme_file_uri

Mit der neuen Funktion get_theme_file_uri() wird ähnlich wie bei get_template_directory_uri und get_stylesheet_directory_uri die URL zum Theme Ordner zurückgegeben. Der typische Anwendungsfall im WordPress Theme ist deshalb das Einbinden von CSS und JavaScript.

Das Neue an der Funktion ist, dass mit Verwendung von get_theme_file_uri überprüft wird, ob die Datei im Child Theme existiert. Falls nicht, wird als Fallback auf die Datei im Parent Theme zurückgegriffen.

Dazu wird der relative Pfad zur Datei im Theme Ordner als Parameter übergeben, und nicht wie bisher als String angehängt. Als Rückgabe erhalten wir eine URL direkt zur Datei, weshalb die Funktion auch ihren Namen hat (file statt directory).

wp_enqueue_script( 'custom-script', get_theme_file_uri( 'js/custom-script.js' ) );

Als Erstes wird versucht, die Datei custom-script.js aus dem Child Theme einzubinden. Falls diese im Child Theme nicht existiert, wird automatisch auf die Datei im Parent Theme zurückgegriffen.

Damit ist es für Theme Entwickler nun möglich, JavaScript und CSS Dateien überschreibbar zu machen, indem diese mit der neuen Funktion get_theme_file_uri anstatt wie früher mit get_template_directory_uri() eingebunden werden.

Nutzer des Themes können die CSS / JS Dateien einfach vom Parent Theme ins Child Theme kopieren und dort Änderungen machen, um die Originaldatei zu überschreiben – genauso wie es seit Langem für Template Dateien funktioniert.

get_theme_file_path

Analog zur neuen Funktion für die Theme Datei URL gibt es auch eine Funktion für die Rückgabe des Theme Dateipfads: get_theme_file_path()

Diese funktioniert auf die gleiche Weise. Die Datei wird als Parameter übergeben, und je nach Existenz der Datei wird der Pfad zum Child oder Parent Theme zurückgegeben.

Grundsätzlich kann die Funktion daher zum Laden von PHP Dateien verwendet werden, um diese in einem Child Theme überrschreibbar zu machen.

require get_theme_file_path( '/inc/customizer.php' );

Davon rate ich aber ab.

Zum Laden von Template Dateien sollten immer die existierenden und speziellen Funktionen wie get_template_part() eingesetzt werden.

Und Funktionsdateien wie template-tags.php oder customizer.php sollten meiner Meinung nach überhaupt nicht mit einem Child Theme überschrieben werden können. Jegliche Aktualisierung der Dateien im Parent Theme würden dadurch verloren gehen, was schließlich zu Problemen führen kann. Zum Beispiel wenn durch ein Update des Parent Themes Funktionen hinzugefügt oder verändert werden.

Anstatt ganze Dateien mit vielen Funktionen komplett zu überschreiben, sollten deshalb besser die einzelnen Funktionen im Child Theme durch entsprechende Hooks und Filter modifiziert werden.

Die Funktion ist aber nicht nutzlos. Ein möglicher Anwendungsfall wird bereits im Ankündigungsbeitrag gezeigt:

wp_enqueue_script(
    'custom-script',
    get_theme_file_uri( 'js/custom-script.js' ),
    array(),
    filemtime( get_theme_file_path( 'js/custom-script.js' ) )
);

Dabei wird mithilfe von filemtime die Versionsnummer für die JavaScript Datei automatisch anhand des letzten Bearbeitungsdatums dynamisch generiert. Hierbei wird der absolute Pfad zur Datei benötigt, welche uns get_theme_file_path liefert.

Funktionen für den Parent Theme Ordner

Ergänzend zu diesen beiden neuen Funktionen wurden mit get_parent_theme_file_uri() und get_parent_theme_file_path() auch zwei Funktionen zur Rückgabe von Theme Datei URL bzw. Theme Dateipfad für Dateien des Parent Theme Ordners eingeführt.

Diese sind als Ersatz für get_template_directory und get_template_directory_uri vorgesehen. Technisch bieten sie keine Neuerungen und erfüllen den gleichen Zweck.

Eingesetzt werden sie aber wie die get_theme_file_* Funktionen, d.h. die Datei wird als Parameter übergeben. Als Rückgabe erfolgt nicht der Parent Theme Ordner, sondern die URL/Pfad direkt zur Datei.

get_parent_theme_file_path

Eignet sich zum Laden von Funktionsdateien im Parent Theme.

Die folgende Zeile mit der alten Implementierung

require get_template_directory() . '/inc/customizer.php';

entspricht der Zeile

require get_parent_theme_file_path( '/inc/customizer.php' );

unter Verwendung der neuen Funktion.

get_parent_theme_file_uri

Um CSS oder JavaScript des Parent Themes einzubinden, ohne ein Überschreiben der Dateien zu erlauben, kann statt get_template_directory_uri nun auch die neue Funktion verwendet werden:

wp_enqueue_script( 'customize-controls', get_parent_theme_file_uri( '/js/customize-controls.js' ) );

Fazit

Ich mag die neuen Funktionen.

Die Namen beschreiben die Funktionen viel verständlicher, was insbesondere den verwirrenden Unterschied zwischen stylesheet und template directory verbessern sollte. Die Implementierung mit Funktion und Parameter finde ich auch lesbarer als die bisherige Verknüpfung von Funktion und Dateinamen als Text String.

TwentySeventeen setzt schon vollständig auf die neuen Funktionen. Da die Default Themes üblicherweise den Maßstab und Best Practices in der Theme Entwicklung setzen, werden wir vermutlich die neuen Funktionen in Zukunft öfter sehen.

Der größte Nachteil im Moment ist, dass diese erst mit WordPress 4.7 zur Verfügung stehen. Mit ein Grund dafür, dass TwentySeventeen nicht mit früheren WordPress Versionen funktioniert. Falls das Theme auch noch mit WordPress 4.6 und früher laufen soll, müssen weiterhin die alten Funktionen genutzt werden.