Layouts and overrides

A layout is a PHP file with HTML markup that prints ready data. Joomla keeps layouts apart from code, in the tmpl folder, and lets you replace any of them with a copy in the site template. This is how a site owner changes the look of an extension without touching its files.

Where layouts live

The default layout is always called default.php.

A second layout

A module can have several layouts. Next to default.php create the file compact.php:

modules/mod_hello/tmpl/
├── default.php
└── compact.php          new file

<?php
// modules/mod_hello/tmpl/compact.php
 
defined('_JEXEC') or die;
?>
<p class="mod-hello mod-hello--compact">
    <?php echo htmlspecialchars($greeting, ENT_QUOTES, 'UTF-8'); ?>
    (<?php echo count($articles); ?>)
</p>

This layout prints the greeting and the number of articles in one line — without the list.

Choosing the layout in the settings

To let the administrator pick a layout, add a field of type modulelayout named layout to the manifest:

<!-- modules/mod_hello/mod_hello.xml, inside fields name="params" -->
<fieldset name="advanced">
    <field name="layout" type="modulelayout" label="JFIELD_ALT_LAYOUT_LABEL"
           class="form-select" />
</fieldset>

The Advanced tab of the module form gets a Layout list with the options default and compact. Choose compact, save and reload the site — the block is now a single line. The dispatcher reads the layout parameter itself and includes the right file.

Overriding in the template

To change the output on a particular site, copy the layout into the html folder of the active template:

modules/mod_hello/tmpl/default.php
        ↓ copy
templates/cassiopeia/html/mod_hello/default.php

Joomla looks for a layout in the template first and only then in the extension. Change the p tag to h4 in the copy and reload the site — the greeting became a heading while the module file stayed the same. Updating the module does not touch the copy.

The copy can also be created from the panel: System → Site Templates → Cassiopeia, the Create Overrides tab — pick mod_hello there.

Override paths

A file with a new name, for example html/mod_hello/wide.php, becomes one more option in the Layout list.

Common mistake

You edit modules/mod_hello/tmpl/default.php and nothing changes on the site. The reason: the template already holds an override, and Joomla uses it. Check the folder templates/cassiopeia/html/mod_hello: if the file is there, it is the one in effect.