Eigene JavaScript- und CSS-Dateien im bluetronix CMS einbinden
In diesem Tutorial bindest du eine eigene JavaScript-Datei und ein eigenes Stylesheet in das Layout deiner Webseite ein. Du lernst die _own-Regel kennen und erfährst, wie die Dateiversionierung bei Änderungen hilft.
Voraussetzungen und Ziel
Für dieses Tutorial benötigst du einen Entwicklerzugang zum bluetronix CMS und solltest den Aufbau der Layouts und Entwicklerordner kennen. Du lernst, eigene JavaScript- und CSS-Dateien zusätzlich zu den vorhandenen CMS-Dateien einzubinden, ohne die originalen Systemdateien zu verändern.
Wir verwenden die in den Screenshots gezeigten Dateien BxHeadScript_own.js und BxStyle_own.css. Beide Dateien werden ausdrücklich im Layout eingebunden, damit das CMS sie beim Laden der Webseite berücksichtigt.
1. Layout öffnen
Öffne im CMS den Bereich Layout und wähle Layout - HTML. Öffne anschließend das Layout, in das du deine JavaScript- und CSS-Dateien einbinden möchtest. In diesem Beispiel verwenden wir das Standard-Layout.
In der Layout-Definition findest du bereits Einbindungen für die zentralen CMS-Dateien, beispielsweise BxHeadScript.js und BxStyle.css. Zusätzliche eigene Dateien kannst du direkt daneben eintragen.
2. Eigene JavaScript-Datei im Dateimanager anlegen
Öffne den Datei-Manager und wechsle in den rot markierten Systemordner bx_script. Dort findest du die zentralen JavaScript-Dateien des bluetronix CMS und gegebenenfalls sprachabhängige Varianten.
Lege dort die eigene Datei BxHeadScript_own.js an oder wähle sie aus, wenn sie bereits vorhanden ist. Du kannst dafür eine geeignete vorhandene Datei als Vorlage kopieren.
Wähle Bearbeiten, um den JavaScript-Code deiner eigenen Datei im Texteditor zu öffnen.
Im gezeigten Beispiel enthält die Datei eigenen JavaScript-Code für die Auswahl zwischen Dark Mode und Light Mode. Im Texteditor kannst du deinen projektspezifischen JavaScript-Code pflegen und anschließend speichern.
Ändere für eigene Erweiterungen nicht die originale BxHeadScript.js. Dateien innerhalb der bx_-Systemordner können bei CMS-Updates überschrieben werden. Kennzeichne eigene Dateien dort mit _own.
3. Eigene JavaScript-Datei im Layout einbinden
Wechsle zurück zu Layout - HTML. Ergänze deine eigene JavaScript-Datei zusätzlich zur vorhandenen CMS-Datei. Soll dein Skript früh geladen werden, fügst du es wie im Screenshot im head-Bereich nach dem bestehenden Head-Script ein.
<script src="__FV_/bx_script/BxHeadScript_own_min.js__"></script>
<script src="__FV_/bx_script/BxHeadScript_own.js__"></script>
Die zusätzliche Zeile lädt deinen eigenen JavaScript-Code. Das ursprüngliche BxHeadScript.js bleibt unverändert. Der Dateipfad und die Schreibweise der eigenen Datei müssen mit der Datei im Dateimanager übereinstimmen.
4. Eigene CSS-Datei im Dateimanager anlegen
Öffne im Datei-Manager den Systemordner bx_style. Hier befindet sich unter anderem das zentrale Stylesheet BxStyle.css. Für eigene Anpassungen verwenden wir eine separate Datei namens BxStyle_own.css.
Lege die Datei BxStyle_own.css an oder öffne die vorhandene eigene Datei. Die Systemdatei BxStyle.css bleibt dabei erhalten.
Über Bearbeiten kannst du in dieser Datei eigene CSS-Regeln hinterlegen und speichern.
5. Eigene CSS-Datei im Layout einbinden
Öffne erneut Layout - HTML. Im head-Bereich ergänzt du nach dem vorhandenen Stylesheet die eigene CSS-Datei. Die Reihenfolge ist wichtig, wenn eigene Regeln die Standardformatierung überschreiben sollen.
<link rel="stylesheet" href="__FV_/bx_style/BxStyle_own_min.css__">
<link rel="stylesheet" href="__FV_/bx_style/BxStyle_own.css__">
Die Standard-CSS-Datei bleibt bestehen, während du zusätzliche oder abweichende Formatierungen getrennt in BxStyle_own.css verwaltest.
6. JavaScript im Head oder am Seitenende verwenden
JavaScript-Dateien können abhängig von ihrer Aufgabe im head-Bereich oder am Seitenende vor dem schließenden body-Tag eingebunden werden. Die gezeigte BxHeadScript_own.js wird im Head geladen. Für andere Skripte kannst du auch einen eigenen Projektordner verwenden und die Datei später im Layout einbinden.
Beispiel für eine zusätzliche Datei aus einem eigenen Ordner am Seitenende:
<script src="__FV_/bx_script/BxScript_own_min.js__"></script>
<script src="__FV_/script/MyScript.js__"></script>Dieses Beispiel zeigt eine zusätzliche Datei. Möchtest du stattdessen eine Systemdatei durch eine eigene Version ersetzen, musst du die entsprechenden Einbindungen im gewählten Layout bewusst anpassen und prüfen, dass keine benötigten CMS-Funktionen entfallen.
7. Systemordner und eigene Projektordner unterscheiden
Die rot markierten bx_-Ordner gehören zum bluetronix CMS. Eigene Dateien innerhalb dieser Ordner müssen mit _own gekennzeichnet werden, damit sie bei regulären CMS-Updates nicht wie die Systemdateien behandelt werden.
Du kannst eigene JavaScript- und CSS-Dateien alternativ in selbst angelegten Projektordnern ohne bx_-Präfix ablegen, beispielsweise /script/ oder /my_scripts/. Dort ist die Kennzeichnung _own nicht zwingend erforderlich. Den tatsächlichen Pfad musst du dann in deiner Layout-Definition verwenden.
Die Kennzeichnung _own ersetzt nicht die Einbindung im Layout: Eine separat angelegte Datei wird erst geladen, wenn sie über die passende script- oder link-Zeile eingebunden ist.
8. Automatische Dateiversionierung
Bei den gezeigten Layout-Einbindungen verwendet das bluetronix CMS die Kennzeichnung __FV_…__. Darüber kann das CMS einen Versionsparameter anhand des Änderungsdatums ergänzen. Nach einer Änderung lädt der Browser dadurch die aktuelle JavaScript- oder CSS-Datei, statt eine ältere Cache-Version weiterzuverwenden.
Beispiel: Ein ursprünglicher Pfad wie /script/MyScript.js kann nach der Verarbeitung um einen Versionsparameter ergänzt werden. Du musst die Versionsnummer bei entsprechend eingebundenen Dateien nicht selbst in jedem Layout aktualisieren.
9. Änderungen speichern und prüfen
Speichere zunächst die eigenen JavaScript- und CSS-Dateien und anschließend das bearbeitete Layout. Lade deine Webseite neu und überprüfe, ob deine JavaScript-Funktionen ausgeführt und die eigenen CSS-Regeln angewendet werden.
Wenn eine Datei nicht geladen wird, prüfe zuerst den Dateinamen, die Groß- und Kleinschreibung, den Ordnerpfad und die Einbindung im Layout. Sind mehrere Layouts im Einsatz, kontrolliere außerdem, ob du das Layout bearbeitet hast, das der betreffenden Seite zugewiesen ist.
Zusammenfassung
Für eigene Erweiterungen legst du beispielsweise BxHeadScript_own.js im Ordner bx_script und BxStyle_own.css im Ordner bx_style an. Anschließend bindest du beide Dateien in Layout - HTML zusätzlich zu den ursprünglichen CMS-Dateien ein. So bleiben die Standarddateien unverändert, während du projektspezifischen JavaScript- und CSS-Code getrennt verwaltest.
FAQ
was Kunden uns häufig Fragen
Benötige ich einen Entwicklerzugang, um eigene JavaScript- und CSS-Dateien einzubinden?
Ja. Dieses Tutorial richtet sich an Entwickler, die Zugriff auf die Layout-Definition und die Entwicklerordner des bluetronix CMS haben.
Wo finde ich die Einbindungen für JavaScript und CSS?
Öffne Layout und wähle Layout - HTML. Dort kannst du die Einbindungen im gewünschten Layout ergänzen.
Wo speichere ich eine eigene JavaScript-Datei?
Im gezeigten Beispiel legst du BxHeadScript_own.js im Ordner bx_script an und bindest sie zusätzlich zur vorhandenen BxHeadScript.js in das Layout ein.
Wo speichere ich eine eigene CSS-Datei?
Im gezeigten Beispiel liegt die eigene Datei BxStyle_own.css im Ordner bx_style. Im Layout wird sie nach dem bestehenden Stylesheet eingebunden.
Warum sollten eigene Dateien in Systemordnern _own im Namen enthalten?
Rot markierte bx_-Systemordner können bei Updates überschrieben werden. Mit _own kennzeichnest du deine eigenen projektspezifischen Dateien.
Wird eine _own-Datei automatisch geladen, sobald sie angelegt ist?
Nein. Du musst die eigene JavaScript- oder CSS-Datei im gewünschten Layout mit einer passenden script- oder link-Einbindung ergänzen.
Kann ich einen eigenen Ordner statt eines bx_-Systemordners verwenden?
Ja. In einem selbst angelegten Projektordner ohne bx_-Präfix ist _own nicht zwingend erforderlich. Verwende im Layout den tatsächlichen Dateipfad.
Sollte ich meine eigene CSS-Datei vor oder nach der Standarddatei laden?
Im gezeigten Beispiel wird BxStyle_own.css nach BxStyle.css eingebunden. Dadurch können eigene Regeln bei gleicher Spezifität die zuvor geladenen Standardregeln überschreiben.
Wozu dient die Kennzeichnung __FV_…__ in den Dateipfaden?
Das bluetronix CMS kann damit einen Dateiversionsparameter ergänzen, sodass Browser nach einer Änderung die aktuelle Datei laden.
Was überprüfe ich, wenn meine eigene Datei nicht wirksam wird?
Prüfe den Namen der Datei, die Groß- und Kleinschreibung, den angegebenen Pfad sowie die Einbindung und Auswahl des richtigen Layouts.