Cassiopeia: de complete gids voor Joomla's standaard template

1. De basis

1.1 Wat is Cassiopeia?

Cassiopeia is het standaard site-template dat sinds Joomla 4 met elke Joomla-installatie meekomt (de backend gebruikt een eigen template, Atum). Het woont in templates/cassiopeia/ met zijn assets in media/templates/site/cassiopeia/, en het is gebouwd op Bootstrap 5, met toegankelijkheid en prestaties als expliciete ontwerpdoelen: semantische landmarks, toetsenbordvriendelijke navigatie, en standaard geen externe font- of scriptverzoeken.

1.2 De filosofie: een leeg canvas

Cassiopeia ziet er bewust onspectaculair uit. Het probeert geen pagebuilder-thema te zijn; het is een leeg, standaardconform canvas dat jij vormgeeft met template-opties, moduleposities, CSS en overrides. Die soberheid is een feature: er is weinig om tegen te vechten, en alles wat Joomla kan - elke component-view, elke module - rendert er standaard correct in.

1.3 Wanneer Cassiopeia genoeg is (en wanneer niet)

• Genoeg: contentsites, blogs, documentatie, organisatie- en bedrijfssites waar heldere typografie en structuur belangrijker zijn dan visueel vuurwerk. Met een child template en wat CSS draagt Cassiopeia die prima.
• Overweeg iets anders: zwaar vormgegeven marketingsites die met slepen-en-neerzetten gebouwd worden, of projecten die gestandaardiseerd zijn op een template-framework. Zelfs dan is wat je van Cassiopeia leert overdraagbaar: posities, stijlen, overrides en asset-afhandeling werken overal hetzelfde.

In mijn eigen klantprojecten gebruik ik vaak YOOtheme Pro, een commerciele template met een visuele drag-and-drop-builder, wanneer het ontwerp verder gaat dan wat makkelijk met Cassiopeia zou kunnen. Met de builder stel je complete pagina layouts samen zonder PHP-overrides, de functie Dynamic Content haalt Joomla-artikelen en custom fields rechtstreeks in elke layout, en kant-en-klare layouts transformeren een lege site snel naar een afgerond ontwerp. Na de oplevering onderhouden redacteuren de pagina's zelf, zonder voor elke wijziging een ontwikkelaar nodig te hebben. De nadelen: een jaarlijkse licentie, wat vendor lock-in aan de markup van de builder, en iets zwaardere pagina's dan een handmatig gebouwde Cassiopeia child template - voor een slanke contentsite blijft de gratis standaard moeilijk te verslaan.

3. Moduleposities

3.1 De positiekaart

Cassiopeia definieert 18 posities. Het layout-skelet, van boven naar beneden:

topbar
below-top
[ brand ]  menu   search
banner
top-a          (card)
top-b          (card)
┌──────────────┬────────────────────┬───────────────┐
│ sidebar-left │ breadcrumbs        │ sidebar-right │
│    (card)    │ main-top   (card)  │    (card)     │
│              │ [ component ]      │               │
│              │ main-bottom (card) │               │
└──────────────┴────────────────────┴───────────────┘
bottom-a       (card)
bottom-b       (card)
footer

Posities gemarkeerd met (card) gebruiken standaard Cassiopeia's card-chrome: modules renderen daar in een opgemaakte doos met de titel als kaartkop. De structurele posities (topbar, menu, breadcrumbs, footer, ...) gebruiken geen chrome. Sidebars verschijnen alleen wanneer er een module in gepubliceerd is - een lege sidebar kost geen ruimte.

3.2 Drie speciale posities

• debug: waar de debug-console rendert wanneer Debug systeem aanstaat.
• error-403 en error-404: posities die alleen op foutpagina's renderen. Publiceer er een zoekmodule, een sitemap-menu of een vriendelijke eigen HTML-module en je 404-pagina wordt behulpzaam in plaats van een doodlopende weg - zonder code.

3.3 Posities live bekijken

Schakel Voorbeeld moduleposities in bij de Templates-opties en plak ?tp=1 achter een frontend-URL. Elke positie rendert met een kader en zijn naam - de snelste manier om "waar zit top-b nou echt?" te beantwoorden.

Een detail uit de broncode: Joomla leest de parameter met getBool(‘tp’) en het booleaanse filter is een gewone PHP-cast, dus elke waarde behalve 0 of een lege tekenreeks wordt als “aan” beschouwd. ?tp=peter-was-hier schakelt het voorbeeld net zo goed in als ?tp=1 – en, nog verrassender, dat geldt ook voor ?tp=false.

5. Aanpassen met user.css en user.js

5.1 Ingebouwde, update-bestendige eigen code

De asset-definities van Cassiopeia registreren twee optionele bestanden die jij aanmaakt:

media/templates/site/cassiopeia/css/user.css
media/templates/site/cassiopeia/js/user.js

Bestaan ze, dan laadt Joomla ze automatisch - en dankzij hun asset-gewicht laadt user.css na de eigen stylesheet van het template, zodat jouw regels winnen zonder !important-gevechten. Joomla-updates raken deze bestanden nooit aan. Voor kleine en middelgrote aanpassingen - kleuren, witruimte, lettertypen, elementen verbergen - is dit alles wat je nodig hebt.

5.2 Een verstandig startpunt voor user.css

:root {
    --cassiopeia-color-primary: #1a3866;   /* je merkkleur */
    --cassiopeia-color-link: #1a3866;
}

.site-grid {
    row-gap: 2rem;                          /* ademruimte */
}

Cassiopeia stelt zijn ontwerp beschikbaar als CSS custom properties, dus het meeste herstijlen is variabelen herdefinieren in plaats van selectors overschrijven. Bekijk colors_standard.css voor de volledige lijst variabelen die het zet.

5.3 Waar user.css ophoudt

CSS verandert het uiterlijk, niet de markup. Zodra je andere HTML nodig hebt - een andere koppenstructuur, extra wrappers, elementen in andere volgorde - heb je user.css-territorium verlaten en betreed je template overrides (zie het Focus On-artikel over template overrides). En groeien je aanpassingen voorbij een handvol bestanden, verzamel ze dan in een child template.

7. Templatestijlen in de praktijk

7.1 Een template, veel stijlen

Een template-stijl is een opgeslagen set optiewaarden. Dupliceer de stijl van Cassiopeia (of het child) in Systeem → Site-templatestijlen, wijzig de opties - een ander logo, vloeiend in plaats van statisch, een ander kleurenschema - en wijs hem toe aan specifieke menu-items via het tabblad Menutoewijzing van de stijl. Joomla rendert die pagina's dan met de andere stijl.

7.2 Wat stijlen oplossen

• Een landingspagina-sectie met een vloeiende, volledige-breedte-layout terwijl de rest statisch blijft.
• Een campagne- of submerk-gedeelte met eigen logo en kleuren.
• Een rustige, afleidingsvrije stijl voor documentatiepagina's.

Stijlen kosten niets tijdens runtime en hebben geen extra bestanden nodig - het zijn rijen in #__template_styles met een JSON-kolom params. Voordat je een heel template dupliceert voor een visuele variant: kijk of een tweede stijl het werk doet.

9. Onder de motorkap (ontwikkelaarsblik)

9.1 De bestandsanatomie

9.2 De Asset Graph

Cassiopeia is een schoolvoorbeeld van de Web Asset Manager. Zijn joomla.asset.json definieert benoemde assets met afhankelijkheden: template.cassiopeia.ltr/.rtl (de hoofdstylesheet per tekstrichting), template.active (een alias die het framework naar het actieve template vertaalt), en template.user - het user.css/user.js-paar uit sectie 5, gedeclareerd met gewicht 500 zodat het als laatste laadt. Moet je eigen extensie na de CSS van het template laden, maak hem dan afhankelijk van template.active in plaats van bestandspaden hard te coderen.

9.3 index.php lezen

De index.php van het template is kort en leesbaar, en drie details zijn een blik waard: de logo-terugvalketen (afbeelding, dan siteTitle, dan sitenaam - exact de volgorde uit sectie 2.2), de voorwaardelijke wrappers die de markup van een positie alleen renderen wanneer er een module gepubliceerd is, en de keuzes style="card" versus style="none" per positie. Bouw je je eigen template- of child-index.php, dan is Cassiopeia de referentie-implementatie om na te volgen.

9.4 Wat de frontend aandrijft

Bootstrap 5 levert het grid en de componenten, metismenu de menu-interacties - beide lokaal meegeleverd, geen CDN. Het template legt er zijn eigen CSS overheen; er is geen buildstap om op de server te draaien, en niets belt naar huis. Dat is het bewaren waard in je eigen aanpassingen: houd assets lokaal, en je site blijft snel en AVG-stil.

9.5 De SCSS-bronnen

Cassiopeia levert zelfs de bronnen van zijn stylesheet mee: media/templates/site/cassiopeia/scss/ bevat template.scss, template-rtl.scss en offline.scss, die Bootstrap en de eigen partials van het template importeren. De live site compileert ze nooit - die laadt de voorgebouwde CSS - maar ze zijn op twee manieren waardevol: als de gezaghebbende referentie voor hoe de stijlen van het template zijn opgebouwd, en als startpunt voor een volledig eigen build (compileer met een Sass-toolchain in je ontwikkelomgeving en lever het resultaat als stylesheet van je child template). Voor alledaagse aanpassingen blijven user.css en de CSS-variabelen het juiste gereedschap; grijp pas naar een eigen SCSS-build wanneer je feitelijk je eigen template op het fundament van Cassiopeia ontwerpt.

11. Cassiopeia en de Web Services API

Templatestijlen - inclusief elke Cassiopeia-optie uit sectie 2 - zijn via REST te beheren. De stijl-endpoints (v1/templates/styles/site) tonen elke stijl met zijn JSON-params, zodat een provisioning-script op afstand een vloeiende landingspagina-stijl kan aanmaken of de standaardstijl van de site kan omschakelen:

curl -H "X-Joomla-Token: <token>" \
     https://example.test/api/index.php/v1/templates/styles/site

De bestanden van het template - user.css, overrides, de html/-map van een child - zijn bestandssysteem-artefacten buiten het bereik van de API; zet ze uit met git of rsync als onderdeel van je normale deployment. En zoals bij alle presentatie: niets van Cassiopeia beinvloedt wat de API teruggeeft - API-antwoorden zijn ruwe data, welk template er ook actief is.

13. Veelvoorkomende fouten en valkuilen

13.1 Cassiopeia's bestanden direct bewerken

Symptoom: eigen CSS of template-bewerkingen verdwenen na een Joomla-update.

Oplossing: Joomla-updates vervangen templates/cassiopeia/ en de bijbehorende mediamap. Doe het werk opnieuw in de update-bestendige lagen: user.css, een child template, overrides. Dan gebeurt het nooit meer.

13.2 user.css laadt niet

Symptoom: het bestand bestaat, maar er verandert niets.

Oplossing: controleer de exacte locatie en naam: media/templates/site/cassiopeia/css/user.css (of de mediamap van het child wanneer een child-stijl actief is - een user.css in de parent wordt voor een child niet geladen). Leeg daarna de cache en forceer een browserverversing.

13.3 De logo-opties vechten met elkaar

Symptoom: je stelt een titel in maar er verschijnt een afbeelding, of de sitenaam verschijnt in plaats van je titel.

Oplossing: onthoud de volgorde: afbeelding wint van titel wint van sitenaam. Maak het veld logoFile leeg als je de teksttitel wilt; zet brand uit om het blok helemaal te verbergen.

13.4 Modules zonder kader (of met een kader te veel)

Symptoom: een module rendert met een onverwachte kaart, of zonder de kaart die je wilde.

Oplossing: de positie bepaalt de standaard-chrome (sectie 3.1), en elke module kan dat overschrijven onder Geavanceerd → Modulestijl. Zet hem expliciet op card of noCard wanneer de positiestandaard niet past.

13.5 De parent aanpassen terwijl een child actief is

Symptoom: overrides of CSS toegevoegd aan Cassiopeia hebben geen effect.

Oplossing: de actieve stijl hoort bij het child, en de bestanden van het child winnen. Verplaats de aanpassing naar het child - waar hij toch al thuishoorde.

13.6 Een pagebuilder verwachten

Symptoom: frustratie dat Cassiopeia "zo weinig instellingen" heeft vergeleken met commerciele templates.

Oplossing: de instellingen van Cassiopeia zijn bewust beperkt; de kracht zit in stijlen, posities, user.css en overrides. Investeer een dag in die vier mechanismen en je hebt meer controle dan de meeste template-controlepanelen geven - met minder afhankelijkheid.

15. In het kort

BESTANDEN    templates/cassiopeia/            index.php, manifest, html/
             media/templates/site/cassiopeia/ css, js, fonts
             eigen bestanden: css/user.css + js/user.js
             (laden als laatste, update-bestendig)

OPTIES       brand / logoFile / siteTitle / siteDescription
             logovolgorde: afbeelding > titel > sitenaam
             fluidContainer, stickyHeader, backTop
             useFontScheme (lokale Roboto), colorName (standard/alternative)

POSITIES     topbar below-top menu search banner
             top-a top-b (card)
             sidebar-left | breadcrumbs main-top [component]
             (card)       | main-bottom (card)  | sidebar-right (card)
             bottom-a bottom-b (card) footer
             speciaal: debug, error-403, error-404
             preview: ?tp=1 (inschakelen bij Templates-opties)

MENU         html/mod_menu: dropdown-metismenu (horizontaal)
                            collapse-metismenu (verticaal)
             search-positie = compact zoekvak in de header

CHILD        manifest: inheritable = 1
             Systeem > Site-templates > Child template aanmaken
             child html/ + child user.css winnen van de parent

STIJLEN      stijl dupliceren > opties wijzigen > Menutoewijzing
             opgeslagen in #__template_styles (params-JSON)
             API: v1/templates/styles/site

CHROMES      card (doos, titel als kop) / noCard
             per module: Geavanceerd > Modulestijl

REGELS       nooit cassiopeia-bestanden bewerken -
             child/user.css/overrides
             assets lokaal, afhankelijk van template.active