Eigen JavaScript- en CSS-bestanden in bluetronix CMS inladen
In deze tutorial laad je een eigen JavaScript-bestand en een eigen stylesheet in de lay-out van je website. Je leert de _own-regel kennen en ontdekt hoe bestandversiebeheer helpt bij wijzigingen.
Vereisten en doel
Voor deze tutorial heb je een ontwikkelaarsaccount voor het bluetronix CMS nodig en moet je de structuur van de lay-outs en ontwikkelmappen kennen. Je leert hoe je eigen JavaScript- en CSS-bestanden kunt integreren naast de bestaande CMS-bestanden, zonder de originele systeembestanden te wijzigen.
We gebruiken de in de screenshots getoonde bestanden BxHeadScript_own.js en BxStyle_own.css. Beide bestanden worden expliciet in de lay-out opgenomen, zodat het CMS ze bij het laden van de website in overweging neemt.
1. Lay-out openen
Open in het CMS het gedeelte Lay-out en kies Lay-out - HTML. Open vervolgens de lay-out waarin je jouw JavaScript- en CSS-bestanden wilt integreren. In dit voorbeeld gebruiken we de standaardlay-out.
In de lay-outdefinitie vind je al invoegingen voor de centrale CMS-bestanden, bijvoorbeeld BxHeadScript.js en BxStyle.css. Aanvullende eigen bestanden kun je direct ernaast invoegen.
2. Eigen JavaScript-bestand aanmaken in de bestandsbeheerder
Open de Bestandsbeheerder en ga naar de rood gemarkeerde systeemmap bx_script. Daar vind je de centrale JavaScript-bestanden van het bluetronix CMS en mogelijk taalafhankelijke varianten.
Maak daar je eigen bestand BxHeadScript_own.js aan of kies het als het al bestaat. Je kunt hiervoor een geschikt bestaand bestand als sjabloon kopiëren.
Kies Bewerken om de JavaScript-code van je eigen bestand in de teksteditor te openen.
In het getoonde voorbeeld bevat het bestand eigen JavaScript-code voor de keuze tussen Donkere modus en Lichte modus. In de teksteditor kun je jouw project-specifieke JavaScript-code onderhouden en vervolgens opslaan.
Wijzig voor eigen uitbreidingen het originele BxHeadScript.js niet. Bestanden binnen de bx_-systeemmappen kunnen bij CMS-updates worden overschreven. Markeer eigen bestanden daar met _own.
3. Eigen JavaScript-bestand in de lay-out inladen
Ga terug naar Lay-out - HTML. Voeg je eigen JavaScript-bestand toe naast het bestaande CMS-bestand. Als je wilt dat je script vroeg wordt geladen, voeg je het zoals in de screenshot in het head-gedeelte in na het bestaande Head-script.
<script src="__FV_/bx_script/BxHeadScript_own_min.js__"></script>
<script src="__FV_/bx_script/BxHeadScript_own.js__"></script>
De extra regel laadt jouw eigen JavaScript-code. Het originele BxHeadScript.js blijft onveranderd. Het bestandspad en de naamgeving van je eigen bestand moeten overeenkomen met het bestand in de bestandsbeheerder.
4. Eigen CSS-bestand aanmaken in de bestandsbeheerder
Open in de Bestandsbeheerder de systeemmap bx_style. Hier bevindt zich onder andere het centrale stylesheet BxStyle.css. Voor eigen aanpassingen gebruiken we een apart bestand genaamd BxStyle_own.css.
Maak het bestand BxStyle_own.css aan of open het bestaande eigen bestand. Het systeem bestand BxStyle.css blijft daarbij behouden.
Via Bewerken kun je in dit bestand eigen CSS-regels toevoegen en opslaan.
5. Eigen CSS-bestand in de lay-out inladen
Open opnieuw Lay-out - HTML. In het head-gedeelte voeg je na het bestaande stylesheet je eigen CSS-bestand toe. De volgorde is belangrijk als je eigen regels de standaardopmaak moeten overschrijven.
<link rel="stylesheet" href="__FV_/bx_style/BxStyle_own_min.css__">
<link rel="stylesheet" href="__FV_/bx_style/BxStyle_own.css__">
Het standaard-CSS-bestand blijft bestaan, terwijl je aanvullende of afwijkende opmaak gescheiden in BxStyle_own.css beheert.
6. JavaScript gebruiken in de head of aan het einde van de pagina
JavaScript-bestanden kunnen afhankelijk van hun functie in het head-gedeelte of aan het einde van de pagina voor de sluitende body-tag worden opgenomen. De getoonde BxHeadScript_own.js wordt in de Head geladen. Voor andere scripts kun je ook een eigen projectmap gebruiken en het bestand later in de lay-out opnemen.
Voorbeeld van een aanvullend bestand uit een eigen map aan het einde van de pagina:
<script src="__FV_/bx_script/BxScript_own_min.js__"></script>
<script src="__FV_/script/MyScript.js__"></script>Dit voorbeeld toont een aanvullend bestand. Wil je in plaats daarvan een systeem bestand door een eigen versie vervangen, dan moet je de overeenkomstige invoegingen in de gekozen lay-out bewust aanpassen en controleren dat er geen benodigde CMS-functies wegvallen.
7. Systeemmappen en eigen projectmappen onderscheiden
De rood gemarkeerde bx_-mappen behoren tot het bluetronix CMS. Eigen bestanden binnen deze mappen moeten met _own worden gemarkeerd, zodat ze bij reguliere CMS-updates niet als systeem bestanden worden behandeld.
Je kunt eigen JavaScript- en CSS-bestanden ook in zelf aangemaakte projectmappen zonder bx_-voorvoegsel opslaan, bijvoorbeeld /script/ of /my_scripts/. Daar is de markering _own niet strikt noodzakelijk. Het daadwerkelijke pad moet je dan in je lay-outdefinitie gebruiken.
De markering _own vervangt niet de invoeging in de lay-out: Een apart aangemaakt bestand wordt pas geladen wanneer het via de passende script- of link-regel is opgenomen.
8. Automatische bestandsversie
Bij de getoonde lay-out-integraties gebruikt het bluetronix CMS de markering __FV_…__. Hierdoor kan het CMS een versienummer toevoegen op basis van de wijzigingsdatum. Na een wijziging laad de browser daardoor het actuele JavaScript- of CSS-bestand in plaats van een oudere cacheversie.
Voorbeeld: Een oorspronkelijke pad zoals /script/MyScript.js kan na verwerking worden aangevuld met een versienummer. Je hoeft het versienummer van overeenkomstig ingesloten bestanden niet zelf in elke lay-out bij te werken.
9. Wijzigingen opslaan en controleren
Sla eerst je eigen JavaScript- en CSS-bestanden op en daarna de bewerkte lay-out. Laad je website opnieuw en controleer of je JavaScript-functies worden uitgevoerd en je eigen CSS-regels worden toegepast.
Als een bestand niet wordt geladen, controleer dan eerst de bestandsnaam, het hoofdlettergebruik, het mappad en de integratie in de lay-out. Als er meerdere lay-outs in gebruik zijn, controleer dan ook of je de lay-out hebt bewerkt die aan de betreffende pagina is toegewezen.
Samenvatting
Voor eigen uitbreidingen maak je bijvoorbeeld BxHeadScript_own.js aan in de map bx_script en BxStyle_own.css in de map bx_style. Vervolgens voeg je beide bestanden in Layout - HTML toe aan de oorspronkelijke CMS-bestanden. Op deze manier blijven de standaardbestanden onveranderd, terwijl je project-specifieke JavaScript- en CSS-code gescheiden beheert.
FAQ
wat klanten ons vaak vragen
Heb ik ontwikkelaars toegang nodig om eigen JavaScript- en CSS-bestanden in te voegen?
Ja. Deze handleiding is gericht op ontwikkelaars die toegang hebben tot de lay-outdefinitie en de ontwikkelaarsmappen van het bluetronix CMS.
Waar vind ik de integraties voor JavaScript en CSS?
Open Layout en kies Layout - HTML. Daar kun je de integraties in de gewenste lay-out aanvullen.
Waar sla ik een eigen JavaScript-bestand op?
In het getoonde voorbeeld maak je BxHeadScript_own.js aan in de map bx_script en voeg je deze toe aan de bestaande BxHeadScript.js in de lay-out.
Waar sla ik een eigen CSS-bestand op?
In het getoonde voorbeeld bevindt het eigen bestand BxStyle_own.css zich in de map bx_style. In de lay-out wordt het na het bestaande stylesheet geïntegreerd.
Waarom moeten eigen bestanden in systeemmappen _own in de naam bevatten?
Rood gemarkeerde bx_-systemappen kunnen bij updates worden overschreven. Met _own markeer je je eigen project-specifieke bestanden.
Wordt een _own-bestand automatisch geladen zodra het is aangemaakt?
Nee. Je moet het eigen JavaScript- of CSS-bestand in de gewenste lay-out met een geschikte script- of link-integratie aanvullen.
Kan ik een eigen map gebruiken in plaats van een bx_-systemap?
Ja. In een zelf aangemaakte projectmap zonder bx_-voorkeur is _own niet verplicht. Gebruik in de lay-out het werkelijke bestands pad.
Moet ik mijn eigen CSS-bestand voor of na het standaardbestand laden?
In het getoonde voorbeeld wordt BxStyle_own.css na BxStyle.css ingeladen. Hierdoor kunnen eigen regels bij dezelfde specificiteit de eerder geladen standaardregels overschrijven.
Waardoor dient de markering __FV_…__ in de bestandsroutes?
Het bluetronix CMS kan daarmee een bestandsversienummer aanvullen, zodat browsers na een wijziging het actuele bestand laden.
Wat moet ik controleren als mijn eigen bestand niet effect heeft?
Controleer de naam van het bestand, het hoofdlettergebruik, het opgegeven pad en de integratie en selectie van de juiste lay-out.