Die wichtigsten URL und Dateipfad Funktionen für WordPress Theme Entwickler im Überblick

Als Einsteiger in die WordPress Theme Entwicklung können die vielfältigen Funktionen zur Rückgabe der Theme Ordner URL bzw. des Dateipfads am Anfang etwas verwirrend sein. In diesem Beitrag möchte ich deshalb einen Überblick über die verschiedenen URL und Pfad Funktionen in WordPress und ihre Verwendung geben.

Unterschied zwischen URL und Pfad

In WordPress gibt es sowohl Funktionen zur Rückgabe des absoluten Pfads zum Theme Ordner, als auch Funktionen zur Ausgabe der Theme Ordner URL. Beide Arten sind für Theme Entwickler wichtig.

Den absoluten Pfad kann man sich als lokalen Speicherort der Theme Dateien auf dem Webserver vorstellen (z.B.  /home/user/public_html/wp-content/themes/). Dieser wird beispielsweise benötigt, um PHP Dateien im Theme zu laden und intern auf dem Server auszuführen.

JavaScript-, CSS- und Bild-Dateien werden üblicherweise mit der URL eingebunden (z.B. https://domain.com/wp-content/themes/), anstatt einen internen Pfad zu verwenden. Der Grund: Die Dateien werden nicht wie PHP Dateien auf dem Server verarbeitet, sondern von außen vom Browser geladen und von diesem verwendet.

WordPress URL und Pfad Funktionen im Überblick

WordPress hat vier Standard-Funktionen für die Rückgabe der Theme URL bzw. des Theme Pfads, welche sich seit Urzeiten (Version 1.5) im Core befinden.

get_stylesheet_directory und get_stylesheet_directory_uri

Die beiden get_stylesheet_directory Funktionen geben den Pfad/URL des derzeit aktivierten Themes der WordPress Installation zurück. Falls ein Child Theme verwendet wird, verweisen diese Funktionen damit auf den Ordner des Child Themes.

get_stylesheet_directory()
absoluter Pfad zum Child Theme Ordner
z.B. /home/user/public_html/wp-content/themes/child-theme

get_stylesheet_directory_uri()
URL zum Child Theme Ordner
z.B. https://domain.com/wp-content/themes/child-theme

get_template_directory und get_template_directory_uri

Die beiden get_template_directory Funktionen hingegen beziehen sich immer auf das Parent Theme.

get_template_directory()
absoluter Pfad zum Parent Theme Ordner
z.B. /home/user/public_html/wp-content/themes/parent-theme

get_template_directory_uri()
URL zum Parent Theme Ordner
z.B. https://domain.com/wp-content/themes/parent-theme

Anmerkung: In der WordPress Dokumentation ist manchmal auch die Rede von stylesheet directory und template directory. Mit Ersterem ist aufgrund der Funktionen der Ordner des Child Themes gemeint, mit Letzterem der Parent Theme Ordner.

Häufiges Problem: Verwendung eines Child Themes

Ohne Child Theme verweisen alle vier Funktionen auf den gleichen Ordner – den des aktuellen Themes. Es tauchen daher keine Fehler auf, egal ob get_template_directory oder get_stylesheet_directory bzw. deren URL Funktionen verwendet werden.

Häufig wird es erst dann problematisch, wenn ein Child Theme aktiviert wird.

Dann müssen die richtigen Funktionen verwendet werden, um die Dateien zu laden. Mit Verwendung der falschen Funktion wird womöglich auf den falschen Theme Ordner zurückgegriffen, in welchem die Dateien nicht existieren.

Anwendung der Funktionen im WordPress Theme

Wann welche Funktion verwendet wird ist immer situationsbedingt. Im Folgenden möchte ich die typischen Anwendungsfälle zeigen.

Laden von PHP Dateien

Die Funktionen eines WordPress Themes befinden sich in der functions.php. Die meisten Themes sind aber etwas umfangreicher und teilen Funktionen zur besseren Übersichtlichkeit in mehrere Dateien auf.

Deshalb werden in vielen Themes am Ende der functions.php noch weitere Dateien geladen.

require get_template_directory() . '/inc/template-tags.php';
require get_template_directory() . '/inc/customizer.php';

Für das Laden von PHP Dateien benötigen wir den absoluten Pfad, nicht die URL.

Die korrekte Einbindung der Dateien vom (Parent) Theme Ordner erhalten wir daher mit get_template_directory(). Damit funktioniert das Einbinden der Dateien auch noch, wenn Nutzer ein Child Theme erstellen. Mit der Funktion wird weiterhin im Parent Theme nach der Datei gesucht.

Falls du ein Child Theme erstellt und dort eine neue PHP Datei angelegt hast, welche geladen werden soll, musst du folglich get_stylesheet_directory() für die Rückgabe des Pfads des Child Theme Ordners verwenden.

require get_stylesheet_directory() . '/child-theme-options.php';

Es spielt übrigens keine Rolle, ob die Funktionen im Child oder Parent Theme verwendet werden. Der Unterschied zwischen Child & Parent bezieht sich auf den Rückgabewert der Funktionen, nicht in welchem Kontext diese ausgeführt werden.

Exkurs: Für das Laden von Template Dateien stellt WordPress extra Funktionen wie get_template_part() bereit, welche ich bald in einem extra Beitrag vorstellen möchte. Deshalb sollten nur Funktionsdateien auf diese hier beschriebene Weise eingebunden werden.

Einbinden von JavaScript und CSS Dateien

Für externe Dateien, die vom Browser geladen werden, verwenden wir analog die URI Funktionen. Typisch sind hier das Einbinden von JavaScript und CSS Dateien.

wp_enqueue_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js' );
wp_enqueue_style( 'genericons', get_template_directory_uri() . '/genericons/genericons.css' );

Auch hier nutzen wir wieder get_template_directory_uri, weil sich die entsprechenden JS und CSS Dateien im Parent Theme befinden. Häufig besteht ein Child Theme ja nur aus style.css, functions.php und wenigen Template Dateien.

Falls aber neue CSS und JS Dateien im Child Theme hinzugefügt werden, kann stattdessen die Funktion get_stylesheet_directory_uri verwendet werden.

Laden von Bildern

Zur Vollständigkeit halber erwähne ich auch noch das Laden von statischen Bildern, was ich persönlich eher selten in meinen Themes brauche. Ebenfalls wieder mit URL Funktion.

<img src="<?php echo get_template_directory_uri(); ?>/images/image.png" />

Spezielle Funktion für die style.css

Für die Einbindung der style.css kennt WordPress noch eine spezielle Funktion: get_stylesheet_uri()

Diese verknüpft eigentlich nur get_stylesheet_directory() mit dem String /style.css. Trotzdem sollte immer die spezielle Funktion verwendet werden, weil diese den Filter stylesheet_uri bereit stellt und damit Plugins Zugriff auf das Laden der style.css gibt.

wp_enqueue_style( 'twentysixteen-style', get_stylesheet_uri() );

Neue Funktionen in WordPress 4.7

Mit WordPress 4.7 wurden erst kürzlich vier neue Funktionen eingeführt, welche die alten Funktionen ergänzen und teilweise ersetzen. Diese stelle ich nächste Woche in einem eigenen Beitrag vor.

2 Kommentare

  1. Hallo Thomas,

    das genau das was ich den ganzen vormittag suche. Aber irgendwo mach ich einen Fehler oder kopiere den Code an die falsch Position in meine function.php. Bin halt kein Profi ;-(

    Habe ein Child Theme 2015 erstellt und im Child Unterordner /inc die template-tags.php angepasst. Aber ich bekomme es einfach nicht daraus eingebunden. Hab alle Variationen ausprobiert, bekomme immer nur eine weiße Seite.
    Wenn ich die Datei im Parent Theme Ordner ablege passt es und wird dargestellt. Hast Du einen Tipp für mich?

    – – – –
    function child_theme_styles() {
    wp_enqueue_style( ‚parent-style‘, get_template_directory_uri() . ‚/style.css‘ );
    wp_enqueue_style( ‚child-theme-css‘, get_stylesheet_directory_uri() .’/style.css‘ , array(‚parent-style‘));
    }
    add_action( ‚wp_enqueue_scripts‘, ‚child_theme_styles‘ );

    require get_template_stylesheet() . ‚/inc/template-tags.php‘;
    – – – –

    Gruß und Dank für Deine Beiträge und Tipps. Hoffe es ist auch nach 1 Jahr noch aktuell 😉
    Lotta

    1. Hallo Lotta,

      Ja, der Beitrag ist noch aktuell. Eine weiße Seite spricht für einen PHP Fehler. Ich würde deshalb auf dem lokalen Webserver, auf dem das Child Theme entwickelt ist, das WordPress Debugging aktivieren. Das gelingt mit Setzen der WP_DEBUG Konstante in der wp-config.php. Siehe auch https://hootproof.de/fehlerfindung-aktivieren-mit-wp_debug/

      Anschließend sollte statt einer weißen Seite eine genaue Fehlermeldung zu sehen sein, anhand derer sich der Fehler beheben lässt. Das hilft auch bei weiteren Syntaxfehlern, die schnell passieren können.

      Auf den ersten Blick ist die letzte Zeile fehlerhaft. Die Funktion get_template_stylesheet() existiert nämlich nicht. Es müsste get_stylesheet_directory() heißen.

      Viele Grüße,
      Thomas

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.