Child templates in Joomla: change Cassiopeia without losing it at the next update

Every Cassiopeia site gets the same advice sooner or later: do not edit the template files, because the next Joomla update puts them back. That advice is right, and since Joomla 4.1 there is a proper way around it. A child template takes everything from Cassiopeia and lets you replace only the parts you change. Here is how it works and where it stops.

If all you want to change is colours, fonts, a top bar or footer columns, you may not need a child template at all. You can write that CSS yourself, or let our own Kickstart Cassiopeia set it from a module. More on that choice under "When you do not need a child template".

Why editing Cassiopeia directly goes wrong

Cassiopeia is a core template. It is updated together with Joomla, so a security release or a minor update can overwrite index.php, the CSS and the layouts in its folders. Any change you made there is gone, often without anyone noticing until a client asks why the header looks different.

Copying the whole template under a new name avoids that, but you then have a fork. Fixes and accessibility improvements that land in Cassiopeia never reach your copy. After a few years you maintain a template nobody else tests.

A child template sits between those two. It contains only the files you change. Everything else is read from the parent at run time, so parent updates keep arriving and your changes stay put.

Creating one

1. Go to System, Templates, Site Templates and open Cassiopeia Details and Files.
2. Click Create Child Template in the toolbar and give it a short name, for example client. Joomla names the result cassiopeia_client.
3. Go to Site Template Styles. Check that there is a style for the child template; if not, create one from the child. Open it, set your colours, logo and brand settings, and make it the default style or assign it to the menu items that should use it.
4. Load the front end and check that nothing changed. At this point the child has no files of its own, so the site should look exactly like Cassiopeia did.

That last check matters. If the site looks different, the child style has different parameters than the old Cassiopeia style. Compare the two Advanced tabs before you start changing files.

Where the files live

The child gets two folders:

• templates/cassiopeia_client/ for templateDetails.xml, layout overrides in html/, and an index.php if you decide to copy one.
• media/templates/site/cassiopeia_client/ for CSS, JavaScript and images.

The templateDetails.xml of the child contains a <parent>cassiopeia</parent> line. That line is what makes the fallback work: when Joomla looks for a file and the child does not have it, it takes the one from Cassiopeia.

What to put in the child

Most sites need surprisingly little:

• A user.css. Cassiopeia loads css/user.css if it exists. Create it in the child's media folder and put your CSS there. The same goes for js/user.js.
• Layout overrides. Create overrides from the child template's editor, under the Create Overrides tab. They land in the child's html/ folder, so you no longer mix your overrides with core files.
• Your own images and fonts in the child's media folder, referenced from user.css.

Copy index.php only when you need to change the structure of the page itself, such as adding a module position or moving the header. Be aware of the trade-off: from that moment on, your copy of index.php wins, and changes the Joomla project makes to Cassiopeia's index.php no longer reach the site. Keep a note of the Joomla version you copied it from, and compare the two after a major update.

When you do not need a child template

If all you want is a few CSS rules, a child is optional. Cassiopeia also picks up media/templates/site/cassiopeia/css/user.css, and Joomla updates do not ship that file, so it survives. A child becomes worth it once you have layout overrides, your own index.php, or more than one site look to manage.

Limits to know about

• Only templates that declare themselves inheritable can have children. Cassiopeia and the administrator template Atum do. Third-party templates vary; check the developer's documentation.
• A child cannot have its own child. There is one level.
• Overrides that already exist in templates/cassiopeia/html/ are not moved for you. Copy them to the child, test, and then delete the originals.
• Template parameters belong to the style, not the files. Moving to the child style means setting them again, which is why the comparison in step four is worth the minute it takes.

A short checklist

• No custom changes left in templates/cassiopeia/ or its media folder, except a deliberate user.css.
• The child style is the default, or assigned where it should be.
• CSS lives in the child's user.css, overrides in the child's html/ folder.
• If the child has its own index.php, the Joomla version it was copied from is written down.

Set it up once, and the next Joomla update is something you install instead of something you repair afterwards.