Joomla Template Overrides and Alternative Layouts

Everything that ends up in the page through a PHP template file can be overridden if the extension loads it in the standard way. There are four families, each with its own folder name in the template’s html folder.

A few conventions are worth remembering:

The lookup differs slightly for views, modules, plugins and layouts, but the idea is always the same: look in the active template first, then in its parent, then in the extension. Because Tallpine uses a child template, the order includes two template folders. The figure summarises the four families; the sections below explain each branch with the source that implements it.

The manager copies the files for you, so the structure is right the first time.

The folder mapping used by the copy step is simple. A module goes to html/<module>; a component view to html/<component>/<view>; a component’s own layouts folder to html/layouts/<component>/<layout>; a plugin to html/plg_<group>_<plugin>; the shared layouts to html/layouts/<group>/<layout>. If the target file already exists, the manager keeps both: the new copy is written with a timestamp in the name, for example default-20261030-101500.php. Those stray files are not loaded (the lookup wants default.php), but they clutter the template, so remove them.

Source: Joomla User Guide: Template overrides

A Cassiopeia site ships overrides for layouts (the module chromes), mod_custom, mod_menu and tinymce, but none for com_content. The Tallpine child template therefore starts with an almost empty html folder, and each override is a deliberate decision.

The article view is the most common override. The core file prints the title, the info block, the images, the text, the tags and the plugin events. Anything the override leaves out disappears from the page, so the safest approach is to copy the core file and change a few lines. The example below keeps every event output of the core file and adds a trail facts block fed by the custom fields of the article (distance-km, elevation-gain, difficulty, gpx-file). It is simplified: the core file also prints icons, images and the pagination, which a real copy keeps.

Source: Joomla User Guide: Template overrides for custom fields

Points to check in an override of this kind:

A module override replaces tmpl/default.php of the module (or any other layout file the module offers). A well-written module renders only from variables prepared by its Dispatcher and Helper, so the override can change the markup without touching the data. The next hikes module of the Tallpine package passes $list (an array of objects with title, link and start) to its layout.

Source: Joomla User Guide: Template overrides

The variables available in a module layout are those documented for modules in Module development. The module wrapper (the chrome selected under Advanced → Module Style) is not part of the module override; it comes from html/layouts/chromes, as explained in Layouts and module chromes.

The Developer Manual adds a warning: a module’s own layouts folder (and a plugin’s) is not an override location and is not searched automatically. Layouts rendered by a module or plugin are found only because the caller passes the folder as the base path of LayoutHelper::render().

Few core plugins print anything, and those that do use a tmpl folder. plg_content_pagenavigation prints the previous/next navigation of an article. The Tallpine template wants the links to name the destination (previous and next trail) instead of generic labels.

Source: Joomla User Guide: Template overrides

Plugin overrides show how fragile copies can be. The template file reads variables ($row, $rows, $location) that the plugin’s Extension class sets before it includes the file, and it calls $this->loadLanguage(). When the plugin’s author renames a variable, the override silently prints nothing. That is exactly the kind of change the checker described below is designed to point out. Core plugin classes are final in Joomla 6, so the template file is the only supported extension point for the markup.

Layouts are the small fragments that several views share: the info block (author, category, dates, hits), the read-more button, the intro and full images, the icons, the pagination, the form-field markup and the module chromes. One override changes every place that uses the fragment.

The article info block lists the author, category, publication date and hit counter. The Tallpine board decided that trail reports should show the category and the date but not the author name or the hit counter. Instead of editing the view, the template overrides the shared layout. Because the same layout is used by blog and list views, the override applies there as well.

Source: Joomla Manual: Layouts

The layout ID is translated to a path by replacing dots with slashes: joomla.content.info_block becomes layouts/joomla/content/info_block.php, and its override html/layouts/joomla/content/info_block.php. The sub-layout calls load info_block/category.php and the other parts from the folder named after the parent; they are looked up with the same search order, so each part can also be overridden on its own. Copy those files only when you need to change them.

The three most useful layout families for a themer are:

A template override replaces the default layout for everyone. An alternative layout is a second file in the same folder that applies only where it is selected, which lets one template keep several versions of the same view. The files live in html/<extension folder>/ just like overrides, but they have a different name. Their rules:

The selector shows the file name unless a language key provides a label. The Joomla User Guide names the keys; for modules the selector builds TPL_<TEMPLATE>_<MODULE>_LAYOUT_<NAME> in upper case from the template element, the module and the file name, and the component selectors use the same idea with the component and view. The keys are read from the template’s tpl_<template>.sys.ini language file, and the guide also describes entering them as language overrides.

Source: Joomla User Guide: Template layouts

Custom fields reach a page in three ways, and each can be overridden. The field system is described in Joomla custom fields; this section shows the template side for the trail fields (distance-km, elevation-gain, difficulty, gpx-file, season).

FieldsHelper::render($context, 'field.render', ['field' => $field]) first renders the layout with the component taken from the context (com_content for com_content.article) and, if that produced nothing, renders it again with com_fields. In a template that means the first existing file of these wins: html/layouts/com_content/field/render.php in the child, then in the parent, then components/com_content/layouts/field/render.php, then html/layouts/com_fields/field/render.php, and finally components/com_fields/layouts/field/render.php. The core layout prints the label (span.field-label) when Show Label is on, the prefix, the value (span.field-value) and the suffix, and returns nothing for an empty value. The override below adds a class and a data attribute per field name that the Tallpine stylesheet uses to draw the difficulty badge.

Source: Joomla User Guide: Template overrides for custom fields

The field value is printed unescaped on purpose, because the type plugin has already prepared it (an Editor field is HTML, the others are encoded); an override that escapes it again shows entities, and one that prints rawvalue must escape it. An override of the front-end layout changes only the front-end display; the edit forms in the administrator use their own layouts.

Copying a core file freezes its logic at the version of the day. When a later update fixes a bug, closes a security hole or changes the variables the file uses, the override keeps the old code. Joomla tracks this with three parts.

Reviewing the list is a short routine:

The table has one row per file with the columns template, hash_id (the base64 of the relative path), extension_id, state (0 unchecked, 1 checked), action, client_id, created_date and modified_date.

The checker is useful but narrow. It looks at the original that has the same path as an override, so a file with no counterpart in core, such as compact.php or trailreport.php, is never flagged, even if the code it was based on changed. It depends on the plugin being enabled when the update runs, and the before/after snapshots are kept in the session of the administrator who runs the update. Treat it as an aid and keep your own diff in the release routine (see the script below). In practice, enable both plugins on every site that has overrides, mark the list checked after each review, and look at the dashboard icon after every update.

Source: joomla-cms: Installer - Override plugin

Older books and tutorials describe a manual routine: remember which files you copied and compare them yourself after every update. Joomla! 4 Masterclass (2023) and Developing Extensions for Joomla! 5 (2023) cover overrides and child templates, but they predate several details of Joomla 6. The Updated Files list, the Show Differences panes and the dashboard notification date from Joomla 4.0, and the old component layout (views/article/tmpl) is now tmpl/article. Child templates are not "brand new" either: they have been the standard way to customise Cassiopeia since 4.1, and Joomla 6.0 ships cassiopeia_extended as a core child template.

An override costs a small amount of work on every update. The aim is to have as few as possible and to make the remaining ones easy to review.

Source: Joomla User Guide: Template overrides

The script reports a difference for every override, because an override is supposed to differ; its value is the list it prints for a person to check against the release notes, and its exit status can be ignored in a pipeline that only reports. A more selective variant stores the hash of each core original at the time of copying (for example in an overrides.lock file next to the template) and fails when the hash of the current core file is different. That is the same idea as the Updated Files tab, but it runs in CI before anything is deployed.

Security-wise, an override is ordinary PHP in the web root. It runs with the rights of the web server, can read request data and the database, and is not reviewed by the update process. Treat the template like application code: keep it in version control, escape every value that comes from users or from fields, keep the defined('_JEXEC') or die; guard, avoid file or network access in markup, and restrict who may edit template files in the Templates component, because a user who can edit them can run PHP. File permissions of the templates folder follow the hardening advice in Security hardening, MFA and passkeys.