Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Templates and Extensions

Template Overrides and Child Templates

Change Joomla output without hacking the core: how template overrides, alternative layouts and child templates work, and how to keep them safe through updates.

Sooner or later you want a Joomla page to print different HTML than the one the core produces: an article with a different meta box, a login module with extra markup, a category blog without the date. The wrong way is to edit the file in components/com_content. The next update replaces it and your change disappears, and you may also introduce a security problem by diverging from the maintained code.

Joomla's answer is the template override: you place a modified copy of a layout file inside your template, and Joomla uses it instead of the original. Combined with a child template (available since Joomla 4.1) you get a clean, update-proof place for all your changes. The product cannot run on this site, so this lesson describes the file paths and menus exactly and uses two stand-in programs to show the lookup and the update check.

Where the layouts live

Every extension that outputs HTML separates logic from presentation. The view prepares data; a layout file prints it. The original layouts live next to the extension, for example:

  • components/com_content/tmpl/article/default.php (Joomla 4 and later; older versions used views/article/tmpl)
  • modules/mod_login/tmpl/default.php
  • layouts/joomla/content/info_block.php (shared layouts, loaded with LayoutHelper)

An override mirrors that path inside the template's html folder:

Original Override
components/com_content/tmpl/article/default.php templates/cassiopeia/html/com_content/article/default.php
modules/mod_login/tmpl/default.php templates/cassiopeia/html/mod_login/default.php
layouts/joomla/content/info_block.php templates/cassiopeia/html/layouts/joomla/content/info_block.php

When Joomla needs a layout it checks the active template first and only then falls back to the extension's own file. That is the whole mechanism.

Creating an override

You rarely write the path by hand. In the administrator open System > Site Templates, click the name of your template (for example Cassiopeia) and switch to the Create Overrides tab. It lists components, modules, plugins and layouts. Click an entry, such as com_content > article, and Joomla copies the original files into templates/cassiopeia/html/... for you. Then open the copied file in the Editor tab (or on disk) and edit it.

Edit the copy in small steps and test after each one. A syntax error in a layout can produce a blank page, so keep a way to restore the file, preferably by keeping the template folder in Git.

flowchart LR
    A["Request needs com_content/article/default.php"] --> B{"Override in active template?"}
    B -- "Yes" --> C["Use templates/cassiopeia/html/..."]
    B -- "No" --> D["Use components/com_content/tmpl/..."]

Joomla prefers the template's copy and falls back to the original.

Alternative layouts

An override does not have to replace the default. If you copy a layout under a new name, for example default.php to highlight.php, it shows up as an alternative layout. In an article you pick it in the menu item's Layout dropdown (or in a module's Advanced tab). Now only that menu item uses the new markup and the rest of the site stays unchanged. This is the safest way to experiment, and it is the right choice when two places on the site need two designs.

Child templates

Overrides inside Cassiopeia itself have a drawback: if you update Cassiopeia (it is part of Joomla core, so every Joomla update may change it), your files sit inside a folder the updater manages. A child template separates them.

Open System > Site Templates, click Cassiopeia and use the Create a Child Template button, then give it a name. Joomla creates a new template (for instance cassiopeia_child) that declares Cassiopeia as its parent in its manifest templateDetails.xml. Assign the child's style to your site. The rules:

  • The child template inherits everything from the parent.
  • Put your overrides in the child's html folder; they win over the parent's.
  • Put your custom CSS and JavaScript in the child's own user.css and user.js under its media folder.
  • Parent updates keep arriving, and your files are untouched.

Always create overrides in the child once you have one. Joomla's Create Overrides tab, when you open the child template, writes into the child.

Keeping overrides in step with updates

An override is a snapshot of the core file at the moment you copied it. If a Joomla update fixes a bug or a security issue in the original layout, your copy still has the old code. Joomla helps: after an update, the template's Updated Files tab and a notice on the control panel list overrides whose original changed, and show a diff so you can merge the change by hand.

You can imitate that process in a few lines. Keep a hash of the original at copy time, and compare it with the current core file.

JS Resolving which layout file Joomla uses

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

No output.

This is a stand-in: real Joomla also consults the layout name chosen in the menu item and the JLayout include paths, but the order (child, parent, core) is the same.

JS Spot overrides whose original changed

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

No output.

Practical advice

  • Override as little as you can. A one-line change in a copy of a 300-line layout is still 300 lines you must maintain.
  • Prefer layout options and parameters first: many modules and menu items already offer settings that remove the date or the author without any code.
  • Use CSS to hide something only when security and accessibility do not depend on it; hidden content is still sent to every visitor.
  • Keep overrides in version control and note in a comment which Joomla version you copied from.
  • Escape output. When you print a value in a layout, use $this->escape($value) or htmlspecialchars(); see security hardening.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does the override for components/com_content/tmpl/article/default.php go?

    An override mirrors the extension's path under the template's html folder.
  2. 2. What is the main benefit of a child template?

    The child holds your overrides and CSS, so parent updates do not touch them.
  3. 3. You want one landing page to use different article markup. What is the cleanest approach?

    An alternative layout (a copy with a new name) is selectable per menu item and leaves other pages alone.
  4. 4. Why can an override become a security risk?

    After an update the original may be patched while your copy keeps the old code, so review the Updated Files list.

Summary

  • Never edit core files; copy a layout into the template's html folder instead.
  • The lookup order is child template, parent template, then the extension's own file.
  • Use alternative layouts for per-page variations.
  • A child template (Joomla 4.1+) keeps overrides and custom CSS away from core updates.
  • Review overrides after each update using the Updated Files tab.

Next: Extension Types and the Installer