Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Templates and Extensions

Cassiopeia and Template Styles

Learn how Joomla templates work: Cassiopeia module positions, template styles, assigning styles to menu items, user.css and brand colors that stay readable.

A Joomla template controls how your site looks: the page skeleton, the fonts, the colors and where each module can appear. The content itself (articles, menus, modules) lives in the database and is independent of the template, which is why you can restyle a whole site without rewriting a single article.

Since Joomla 4 the default site template is Cassiopeia and the default administrator template is Atum. This lesson is about Cassiopeia and the idea of a template style, which is how Joomla lets one template look different in different parts of the site. Joomla itself cannot run inside this website, so the menu paths and file names below are described precisely, and the TryIt blocks are small stand-ins that teach the same ideas (page layout and color contrast) in the browser.

Template versus template style

Two words are easy to mix up:

  • A template is code: PHP, CSS, JavaScript and an XML manifest, installed on disk (for Cassiopeia, under templates/cassiopeia and media/templates/site/cassiopeia).
  • A template style is a saved set of options for a template (logo, colors, fonts, layout switches). One template can have many styles.

You find them under System > Site Template Styles. A fresh install has one style, "Cassiopeia - Default", marked with a star (the default style). You can Duplicate it, change the options of the copy, and then decide where the copy is used.

A style is used in one of two ways. The default style applies to every page that has no other instruction. Or you can open a menu item, go to its Template Style tab and choose a different style: every page reached through that menu item (and its children) then uses it. A common use is a darker, simpler style for a landing-page menu item and the normal style for the rest of the site.

flowchart TD
    A["Visitor requests a page"] --> B{"Menu item has its own template style?"}
    B -- "Yes" --> C["Use that style"]
    B -- "No" --> D["Use the default style"]
    C --> E["Template renders positions and modules"]
    D --> E

How Joomla picks a template style for a page.

Style options in Cassiopeia

Open a Cassiopeia style and look at the Advanced tab. The exact list changes between versions, so check your own installation, but you will find options such as:

  • Brand: whether the site name or a logo is shown in the header.
  • Logo File and Site Title/Description: a media image and text used in the header.
  • Colour Name: Standard or Alternative, two built-in palettes (the alternative one suits right-to-left languages as well).
  • Fluid Container: full-width layout instead of a centered column.
  • Sticky Header and Back-to-top link.
  • Options for the header, text, link and background colors and for the font.

Saving a style writes its values as JSON into the #__template_styles table. Template code reads them through $this->params. The important point is that style options live in the database, while the template files stay untouched, so updating Joomla never overwrites your choices.

Module positions

A template defines named positions, empty slots into which administrators place modules. Cassiopeia's positions include topbar, below-top, menu, search, banner, top-a, top-b, main-top, main-bottom, breadcrumbs, sidebar-left, sidebar-right, bottom-a, bottom-b, footer and debug. The article or component output itself is shown in the main area, not in a position.

To see them on a real site, open System > Site Templates > Options (the template options screen) and turn on Preview Module Positions; then add ?tp=1 to any front-end URL, for example https://example.com/?tp=1. Joomla outlines every position and prints its name. Turn the option off again afterwards, because it is a development aid.

A Cassiopeia-like page with positions

The checkbox shows an important behavior: a position with no published module produces no markup, and the layout adapts (in Cassiopeia the main area grows when a sidebar is empty). This is a stand-in made with CSS grid, not Cassiopeia's real code.

Adding your own CSS safely

Never edit template.css in media/templates/site/cassiopeia/css: an update would erase your change. Cassiopeia loads two optional files automatically when they exist:

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

Create them yourself (the file manager of your host, or System > Site Templates > Cassiopeia Details and Files in the admin) and put your overrides there. Cassiopeia exposes its main colors as CSS custom properties, so a brand color is often a two-line change:

CSS
:root {
  --cassiopeia-color-primary: #0b5d4b;
  --cassiopeia-color-link: #0b5d4b;
  --cassiopeia-color-hover: #073d31;
}

Because the files live in your own folder and survive updates, this is the first thing to try before you think about template overrides. Check the variable names in your version's template.css, since they are the template's choice, not a Joomla guarantee.

Choose a readable brand color

A brand color is used for links and buttons, so it must have enough contrast with the background. WCAG asks for a ratio of at least 4.5:1 for normal text. This stand-in calculates the ratio for any two colors, using the WCAG formula.

JS Contrast checker for brand colors

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Change the list of colors and the background to test your own palette before you type it into the template style.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between a template and a template style?

    The template files stay the same. Styles are stored in the database and can be duplicated and assigned to menu items.
  2. 2. Where do you assign a different template style to one part of the site?

    The Template Style tab of a menu item makes that item (and pages reached through it) use the chosen style.
  3. 3. Which URL parameter outlines module positions once Preview Module Positions is enabled?

    Adding ?tp=1 to a front-end URL prints each position name, provided the template option is on.
  4. 4. Why put your CSS in user.css instead of editing template.css?

    Core template files are replaced during updates; your own user.css survives.

Summary

  • A template is code; a template style is a saved option set stored in the database.
  • Assign a non-default style through a menu item's Template Style tab.
  • Cassiopeia offers named positions; empty positions output nothing.
  • Use ?tp=1 (with the preview option on) to see positions, then switch it off.
  • Put custom CSS and JS in user.css and user.js; set brand colors with Cassiopeia's CSS variables and check contrast first.

Next: Template Overrides and Child Templates