Joomla Template Overrides: Change Output Without Core Hacks

1. The Basics

1.1 What is a Template Override?

When Joomla renders a page, every piece of output comes from a small PHP file: an article from the com_content article layout, a menu from the mod_menu layout, a pagination bar from a shared layout file. A template override is a copy of such a file placed inside your template's html/ folder. If the copy exists, Joomla uses it and ignores the original. If not, the original runs.

components/com_content/tmpl/article/default.php     the original (core)
templates/cassiopeia/html/com_content/article/default.php   your override

That is the entire mechanism. No configuration, no registration, no database entry - the file's existence is the override.

1.2 Why Overrides Exist

• Updates stay safe: core files are replaced on every Joomla update; your html/ folder is not touched.
• Any markup becomes yours: you control every class, tag, and attribute without hacking anything.
• They are honest: anyone auditing the site finds all customisations in one predictable place.

1.3 What Can Be Overridden

Cassiopeia itself ships with overrides - look inside templates/cassiopeia/html/ and you find mod_menu layouts (the metismenu dropdowns), a mod_custom banner layout, and two chromes (card.php, noCard.php). The core template uses the same mechanism you will use.

The mechanism also covers third-party extensions: a well-built shop, blog, or events component is overridden as html/com_theircomponent/... and its modules as html/mod_theirmodule/, exactly like core. Whether an extension is cleanly overridable is a useful quality test before you adopt it.

One thing that looks like an override subject but is not: system emails. Registration mails, password resets, and other notifications are customised through the Mail Templates component in the backend - see the Focus On article about mail templates - not through files in html/.

3. How Joomla Finds the Right File

3.1 The Lookup Order

For every view and module, Joomla checks a short list of locations and uses the first file it finds:

1. templates/{child}/html/...      the active child template (if any)
2. templates/{parent}/html/...     the parent template
3. {extension}/tmpl/...            the extension's own layout (the default)

This order explains two important behaviours: a child template can override its parent's overrides, and an extension's own layout is simply the last resort. The active template style decides which template (and therefore which override set) is in play - a site can even use different templates on different menu items.

3.2 Naming is Everything

Overrides are matched purely by path and filename. html/com_content/article/default.php works; html/com_content/Article/default.php or html/content/article/default.php silently does nothing. When an override "does not work", the name or folder is wrong in nine out of ten cases.

3.3 Sublayouts: the Underscore Files

Look inside components/com_content/tmpl/article/ and you find default.php plus default_links.php. The underscore files are sublayouts, loaded from the main file with $this->loadTemplate('links'). They are overridden exactly like the main file - and they let you override just one fragment of a view instead of the whole thing. If your change is inside a sublayout, copy only that file and leave default.php alone: one less file to maintain.

5. Layout Overrides (JLayout)

5.1 The Shared Layouts

Beyond components and modules, Joomla keeps a library of shared layouts in the root layouts/ folder: pagination, custom fields rendering, edit form pieces, buttons, icons. Core code renders them through the LayoutHelper class:

use Joomla\CMS\Layout\LayoutHelper;

echo LayoutHelper::render('joomla.content.info_block.author', ['item' => $this->item]);

5.2 Overriding a Shared Layout

The dot notation maps to a path, and the override mirrors it under html/layouts/:

layouts/joomla/content/info_block/author.php                    original
templates/{template}/html/layouts/joomla/content/info_block/author.php   override

Layout overrides are powerful because shared layouts appear everywhere: override the custom fields layout once (layouts/joomla/content/fields.php and friends) and every component that renders fields picks it up. The same reach makes them worth extra care - test more than one page type after changing a shared layout.

5.3 Choosing the Right Level

The same visual change can often be made in a component override, a module override, or a layout override. Rule of thumb: override at the narrowest level that covers your goal. One article view? Component override. One module instance? A named module layout. A pattern repeated across the site (pagination, field output)? That is what layout overrides are for.

7. Overrides in Child Templates

7.1 Why Overrides Belong in a Child

Since Joomla 4.1, templates can have child templates, and Cassiopeia supports them out of the box. The parent ships the machinery; the child holds your changes: style settings, custom CSS, and overrides. When the parent template is updated, your child - and every override in it - survives untouched. If you build on Cassiopeia today, put your overrides in a child, not in Cassiopeia itself.

7.2 How the Lookup Treats Children

As section 3 showed, the child's html/ folder is checked before the parent's. The practical consequences:

• A child override wins over the same override in the parent.
• The child only needs the files you change; everything else falls through to the parent and then to core.
• Moving an existing site to a child template is mostly moving the html/ folder and the custom CSS.

7.3 Assets Live in media/

Since Joomla 4.1 template assets (CSS, JS, images) live under media/templates/site/{template}/ rather than inside the template folder. Overrides that load assets should use the Web Asset Manager or HTMLHelper::_('stylesheet', ...) with relative paths, so the child/parent fallback also works for the assets themselves.

9. Surviving Updates: Override Maintenance

9.1 The Cost Nobody Mentions

An override is a snapshot of a core file at one moment in time. When a Joomla update improves the original - a bug fix, an accessibility improvement, a security-relevant escape call - your override keeps running the old code. Overrides do not break on updates; they silently fall behind, which is worse, because nothing looks wrong.

9.2 Joomla Tracks This For You

Few people know that Joomla records exactly this. After an update, the #__template_overrides table marks override files whose originals changed, and the template manager shows them as Updated Files ("Updated files to check") with the date of the change. The workflow:

1. After every core update, open System → Site Templates → your template.
2. Check the Updated Files list.
3. For each file, compare your override with the new original (a diff tool makes this quick) and port the relevant changes into your override.
4. Mark the entry as checked (Mark Checked), so the list stays meaningful.

9.3 Make Future Diffs Easy

• Keep overrides minimal: the fewer lines differ from the original, the faster every diff.
• Comment your changes (// changed: moved author line), so future-you knows what to preserve.
• Keep the site - or at least the template folder - in version control. git diff after an update answers most questions instantly.
• Delete overrides you no longer need. The best maintenance is on files that do not exist.

11. Overrides and the Web Services API

Overrides are presentation, and the Web Services API skips presentation entirely: an API request for an article returns raw data from the model, so no component override, chrome, or layout override affects API output. If a headless frontend needs different "markup", that markup lives in the consuming application, not in Joomla overrides.

The API does touch templates at one point: template styles can be managed via REST (v1/templates/styles/site and v1/templates/styles/administrator), so provisioning tools can switch a site's active style - and with it, which template's override set is in use. The override files themselves are filesystem artefacts: deploy them with your normal deployment process (git, rsync), not through an API.

13. Common Mistakes and Pitfalls

13.1 Editing the Core File Instead

Symptom: a customisation vanished after the last Joomla update.

Fix: the change was made in the extension's own tmpl file. Redo it as an override in the template's html/ folder, where updates cannot reach it - that is the entire point of the mechanism.

13.2 The Override That Does Nothing

Symptom: the override file exists, but the page ignores it.

Fix: check, in order: the exact folder and file name (section 3.2), whether the active template style is the template you edited (another style may be assigned to this menu item), whether a child template's own override wins, and finally clear the cache.

13.3 Overriding Everything "While You Are At It"

Symptom: the Updated Files list after a core update shows forty entries; nobody dares to touch any of them.

Fix: delete every override that is identical to its original (a diff shows this in seconds). Keep only real changes, and prefer sublayout and layout overrides over full-view copies.

13.4 Stale Overrides After Updates

Symptom: a bug or accessibility issue that Joomla fixed months ago still appears on your site.

Fix: your override still contains the old code. Adopt the section 9 workflow: check Updated Files after each update and port changes into your overrides. For fixes with security impact, treat this as urgent, not cosmetic.

13.5 Business Logic in the Override

Symptom: an override runs database queries or calls models, and the site slows down or breaks when an extension updates.

Fix: move the logic to where it belongs - a plugin, a module, or the model - and let the override only format the data the view already has.

13.6 Lost Escaping

Symptom: after restyling an override, user-provided content renders as raw HTML.

Fix: restore the $this->escape() / htmlspecialchars() calls from the original file. Styling changes must never remove output escaping.

15. Quick Reference

PATHS        component  html/com_content/article/default.php
             module     html/mod_menu/default.php
             layout     html/layouts/joomla/content/info_block/author.php
             chrome     html/layouts/chromes/mychrome.php

LOOKUP       child html/ > parent html/ > extension tmpl/
             matched by exact path + filename, first hit wins

CREATE       System > Site Templates > template > Create Overrides
             manual: cp from tmpl/ to html/ mirrored path

SUBLAYOUT    default_links.php  = loadTemplate('links')
             override fragments, not whole views

ALTERNATIVE  copy with new name (mycard.php) = selectable layout
             + mycard.xml with metadata = menu item type

CHROME       core: none, html5, outline, table
             cassiopeia: card, noCard
             custom chrome file = new "Module Style" option

MAINTAIN     after each update: template > Updated Files list
             (#__template_overrides tracks changed originals)
             diff override vs new original > port > Mark Checked

RULES        display code only - no queries, no models
             keep $this->escape() intact
             cache cleared before path-doubt debugging

API          overrides do not affect API output (raw data)
             v1/templates/styles/site manages active style only

DEV          tmpl/ + default.xml + sublayouts + LayoutHelper
             = your extension is fully overridable