Wenn man JavaScript und CSS Dateien einbinden möchte, dann sollte man immer die Funktionen wp_enqueue_script() und wp_enqueue_style() verwenden. Falls ihr das noch nicht tut, dann fangt bitte ab sofort damit an. Die Verwendung der beiden Funktionen ist wirklich sehr einfach, aber um diese auch effektiv zu nutzen, sollte man ein paar Dinge beachten.

Einfache Verwendung

Die einfachste Art, die Funktionen zu verwenden, ist die Definition eines „handle“ sowie einer URL der Datei, die ihr einbinden wollt:

wp_enqueue_script(
	'chart-js',
	'https://cdnjs.cloudflare.com/ajax/libs/Chart.js/3.7.0/chart.min.js'
);

Dieses Beispiel würde eine JavaScript-Datei einbinden, sie sich auf einem externen Server befindet. Das ist so weit auch OK, aber es gibt viele Gründe, wieso man Dateien lieber lokal einbinden möchte, um beispielsweise Probleme beim Ausfall des CDN zu vermeiden oder aber, um den Datenschutz zu verbessern.

Verwendung einer lokalen Datei – schlechtes Beispiel

Um eine Datei aus einem Plugin oder Theme zu laden, würde es ausreichen, den Pfad wie folgt relative anzugeben:

wp_enqueue_script(
	'chart-js',
	'/wp-content/plugins/plugin-name/assets/chart.min.js'
);

Die Datei würde dann wie folgt in den Quellcode eingebunden werden:

<script type='text/javascript' src='https://theme-tests.docker.test/wp-content/plugins/plugin-name/assets/chart.min.js?ver=5.9'></script>

Das würde zwar funktionieren, es gibt mit dieser einfachen Methode aber ein paar Probleme.

1. Immer dynamische Pfade verwenden

Im Beispiel oben wurde ein relativer Pfad auf das Verzeichnis wp-content/plugins verwendet. Das mag für viele von euch richtig aussehen, aber der Ordner wp-content kann einen anderen Namen haben (und manche Sicherheits-Plugins tun das auch – obwohl es eine schlechte Idee ist). Ihr solltet daher immer eine Hilfsfunktion verwenden, um den relativen Pfad zu diesem Ordner zu erhalten. Wenn ihr eine Datei in einem Plugin oder Theme einbindet, dann könnt ihr hierzu verschiedene Funktionen verwenden. Diese hier werdet ihr dafür vermutlich in der Regel verwenden:

• Für Plugins: plugins_url() oder plugin_dir_url()
• Für Themes: get_template_directory_uri()
• Für Child-Themes: get_stylesheet_directory_uri()

2. Immer eine Version der Datei angeben

Wie ihr in dem Beispiel oben sehen könnt, fügt WordPress immer eine Versionsnummer an. Wenn ihr selbst keine festlegt, dann wird WordPress immer seine aktuelle Version ans Ende der URL anhängen. Heute würde also 5.9 am Ende stehen. Diese Versionsnummer hat den Zweck, euch beim Caching zu helfen. Da sich eure Dateien aber sicher nicht (nur) dann ändern, wenn eine neue WordPress Version erscheint, solltet ihr hier einen anderen Versions-String verwenden. Das könnte einer der folgenden sein:

• Eine statische Versionsnummer, die der Version des Plugins entspricht
• Ein statisches Änderungsdatum des Plugins
• Ein statisches Änderungsdatum der Datei, die eingebunden werden soll
• Ein dynamisches Änderungsdatum der Datei, die eingebunden werden soll

In der Vergangenheit habe ich oft die erste oder dritte Option verwendet. Aber dabei musste jeder dieser Versions-String (für alle Dateien) immer manuell aktualisiert werden. Dabei vergisst man dann schnell mal einen und der Browser liefert eine alte Datei aus seinem Cache aus. Heutzutage verwende ich daher normalerweise den letzten Ansatz. Das hat auch den Vorteil, dass während der Entwicklung, bei jedem Speichern der Datei immer sichergestellt wird, dass der Browser stets die aktuellste Datei lädt. Ein Beispiel für diesen Ansatz – kombiniert mit dynamischen Pfaden – könnte wie folgt aussehen:

wp_enqueue_script(
	'chart-js',
	plugins_url( 'assets/chart.min.js', __FILE__ ),
	array(),
	filemtime( plugin_dir_path( __FILE__ ) . 'assets/chart.min.js' )
);

Das Resultat der Einbindung der Datei würde dann so aussehen:

<script type='text/javascript' src='https://theme-tests.docker.test/wp-content/plugins/plugin-name/assets/chart.min.js?ver=1644792351' id='chart-js-js'></script>

Wie ihr hier sehen könnt, wurde an das Ende der URL der aktuelle UNIX-Timestamp angehängt. Da sich dieser mit jeder Änderung der Datei ändert, wird der Browser immer die aktuellste Datei laden.

Fazit

Dieser Blogbeitrag behandelt ein sehr einfaches Konzept, aber ich sehe immer wieder Plugins und Themes, die Dateien nicht effektiv einbinden. Mit diesen kleinen Tricks könnte ihr viel Stress beim Finden von Fehlern vermeiden, die nur deshalb auftreten, weil der Fehler eigentlich nur darin bestand, dass der Browser noch immer eine alte Version der Datei aus seinem Cache geladen hatte.