Modules in Joomla

Modules are the small boxes around the main content of a Joomla page: the menu, the login form, the breadcrumbs, the "latest articles" list, the footer.

They look simple in the backend, but underneath they touch positions, page assignment, access control, caching, and a clean structure you can even build yourself.

How Joomla builds, places, and assigns the small blocks around every page.

This article explains how Joomla modules really work. It starts with the basics for website owners and editors, moves on to the practical setup for administrators, and ends with the technical details for developers. You will learn what a module is, how it reaches the page, how to control where it shows, and how to avoid the most common mistakes.

The one idea to take home is this: a page has exactly one component in the middle, but as many modules as you like around it. Learn how one module is assembled, positioned, and assigned, and you can place, override, and build any of them.

2. Site versus Administrator Modules

2.1 Two Clients, One Concept

Modules live in two separate worlds, distinguished by a value called client_id:

public_html/
├── modules/                     ← SITE modules      (client_id = 0)
│   ├── mod_menu/
│   ├── mod_login/
│   └── mod_articles_latest/
└── administrator/
    └── modules/                 ← ADMIN modules     (client_id = 1)
        ├── mod_toolbar/
        ├── mod_quickicon/
        └── mod_submenu/

• Site modules render in the front-end template's positions.
• Administrator modules render in the back-end template, for example the Control Panel dashboards, the toolbar, and the page title.

It is the same architecture and the same file structure. Only the client and the template they plug into differ.

2.2 How a Module Reaches the Page

A module never receives the request. Joomla collects and renders it while the template is being built:

Browser request
   │  index.php?option=com_content&view=article&id=42
   ▼
CMS Application → Router → Component runs, produces the main content
   ▼
Template renders:  <jdoc:include type="component" />   ← the component output
                   <jdoc:include type="modules" name="sidebar-right" />
   ▼
For each module position the template asks for:
   ModuleHelper::getModules('sidebar-right')
      → load published modules for this position
      → filter by access level, language, and menu assignment
      → render each via its Dispatcher + layout
   ▼
Template wraps everything → page sent to browser

The template's <jdoc:include type="modules" name="..."> tags are the sockets. Modules are what you plug into them.

4. Inside a Module (Developer View)

4.1 The Modern Joomla 4/5/6 Folder Layout

Modules are "MVC-lite". There is no Controller and no Model class. Instead a module has a Dispatcher, a Helper, and a layout:

modules/mod_articles_latest/
├── mod_articles_latest.xml      ← manifest (name, version, files, params)
├── services/
│   └── provider.php             ← DI service registration (entry point)
├── src/
│   ├── Dispatcher/
│   │   └── Dispatcher.php        ← prepares the data for the layout
│   └── Helper/
│       └── ArticlesLatestHelper.php  ← the actual data fetching / logic
├── tmpl/
│   └── default.php               ← the HTML layout
└── language/                     ← translation .ini files
    └── en-GB/
        ├── mod_articles_latest.ini
        └── mod_articles_latest.sys.ini

Since Joomla 4 there is no mod_xxx.php entry file at the root. The entry point is services/provider.php, exactly like a component.

4.2 The Manifest (mod_articles_latest.xml)

<extension type="module" client="site" method="upgrade">
    <name>mod_articles_latest</name>
    <version>3.0.0</version>
    <description>MOD_LATEST_NEWS_XML_DESCRIPTION</description>
    <namespace path="src">Joomla\Module\ArticlesLatest</namespace>

    <files>
        <folder module="mod_articles_latest">services</folder>
        <folder>src</folder>
        <folder>tmpl</folder>
    </files>

    <config>
        <fields name="params"> ... the module's Options form ... </fields>
    </config>
</extension>

The key attributes are:

• type="module" and client="site" (or client="administrator").
• <namespace> registers PSR-4 autoloading for src/.
• <config><fields name="params"> defines the form you see in the module editor. Joomla stores the result as JSON in #__modules.params.

4.3 The Entry Point (services/provider.php)

Like components, modules register themselves with the Dependency Injection (DI) container:

return new class () implements ServiceProviderInterface {
    public function register(Container $container)
    {
        $container->registerServiceProvider(
            new ModuleDispatcherFactory('\\Joomla\\Module\\ArticlesLatest')
        );
        $container->registerServiceProvider(
            new HelperFactory('\\Joomla\\Module\\ArticlesLatest\\Site\\Helper')
        );
        $container->registerServiceProvider(new Module());
    }
};

• ModuleDispatcherFactory builds the module's Dispatcher.
• HelperFactory builds Helper objects, with the database injected.
• Module() is the generic module service that ties it together.

There is no manual require and no global state. It is the same modern wiring as a component, just lighter.

4.4 The Dispatcher - Prepare the Data

The Dispatcher has one job: gather the data the layout needs and hand it over.

class Dispatcher extends AbstractModuleDispatcher implements HelperFactoryAwareInterface
{
    use HelperFactoryAwareTrait;

    protected function getLayoutData()
    {
        $data = parent::getLayoutData();   // $data['params'], $data['module'], $data['app']

        $data['list'] = $this->getHelperFactory()
            ->getHelper('ArticlesLatestHelper')
            ->getArticles($data['params'], $this->getApplication());

        return $data;                      // becomes variables in tmpl/default.php
    }
}

Whatever keys you put in $data become $list, $params, $module, and so on inside the layout.

4.5 The Helper - The Logic

The Helper does the real work. Here it queries articles. It receives the database through dependency injection:

class ArticlesLatestHelper implements DatabaseAwareInterface
{
    use DatabaseAwareTrait;

    public function getArticles(Registry $params, SiteApplication $app)
    {
        // Reuse the component's own model - do not reinvent the query:
        $model = $app->bootComponent('com_content')
                     ->getMVCFactory()
                     ->createModel('Articles', 'Site', ['ignore_request' => true]);

        $model->setState('list.start', 0);
        $model->setState('list.limit', (int) $params->get('count', 5));
        // ... apply category, ordering, author filters from $params ...

        return $model->getItems();
    }
}

A good module is thin: it leans on the component's model for data and only handles presentation concerns.

4.6 The Layout (tmpl/default.php)

This is pure presentation. The variables come straight from the Dispatcher's $data:

<?php defined('_JEXEC') or die;

if (!$list) {
    return;                       // nothing to show → render nothing
}
?>
<ul class="mod-articleslatest mod-list">
<?php foreach ($list as $item) : ?>
    <li>
        <a href="/<?php echo $item->link; ?>">
            <?php echo htmlspecialchars($item->title, ENT_QUOTES, 'UTF-8'); ?>
        </a>
    </li>
<?php endforeach; ?>
</ul>

A module can ship multiple layouts in tmpl/, for example default.php and _item.php. Joomla stores the chosen one in the module's layout param.

6. Working with Modules

6.1 Creating and Placing a Module

The standard workflow is:

1. Go to System → Manage → Modules (or Site Modules / Administrator Modules).
2. Click New and pick a module type (mod_custom, mod_menu, ...).
3. Give it a title and choose Show Title.
4. Set the Position: type or pick a template position.
5. Set Menu Assignment: all, none, selected, or all-except.
6. Set Status, Access, Language, and optional publish dates.
7. Configure the type-specific Options (the params form from the manifest).
8. Save. Joomla writes a new row in #__modules.

6.2 Overriding a Module's Output the Right Way

Never edit core module files. Joomla overwrites them on update. Use a template override instead:

Copy:  modules/mod_articles_latest/tmpl/default.php
To:    templates/<your-template>/html/mod_articles_latest/default.php

Overrides survive updates and let you restyle a module without forking its code.

6.3 mod_custom - The Swiss-army Module

This is the single most useful core module: free HTML or text with the editor.

• Drop in a promo banner, a snippet of script, an embedded map, or contact details.
• Combine it with menu assignment for page-specific content.
• Enable Prepare Content in its options so content plugins run inside it, for example {loadposition} style shortcodes or custom-fields output.

When in doubt, a mod_custom plus a template override solves a huge share of "I need a box here that says X" requests.

6.4 Loading a Module Inside Content

Sometimes you want a module within an article, not in a sidebar position:

The {load...} shortcodes are provided by the Content - Load Modules plugin, which must be enabled.

8. Debugging Modules

8.1 The Module-debugging Toolkit

When a module misbehaves (wrong place, no output, stale content), work through these in order:

8.2 The Three Tables to Check

-- Is it published, where, for whom?
SELECT id, title, position, published, access, language
FROM #__modules WHERE module = 'mod_articles_latest';

-- Which pages is it assigned to? (0=all, negative=except)
SELECT moduleid, menuid FROM #__modules_menu WHERE moduleid = 42;

-- Is the extension itself enabled?
SELECT element, enabled FROM #__extensions
WHERE type = 'module' AND element = 'mod_articles_latest';

The classic "module won't appear" checklist is: published? → right position for this template? → assigned to this page? → access level matches the visitor? → language matches? Nine times out of ten it is one of those five.

10. Best Practices

If you only remember a few things from this article, remember these:

• A module is a small presentation block. There can be many per page, and the name always starts with mod_.
• A module has no URL. The template's <jdoc:include type="modules"> sockets and the module's position decide where it appears.
• Menu assignment, access, language, status, and dates decide whether it appears.
• Keep modules thin: the Dispatcher prepares data, the Helper does the logic, the layout renders HTML.
• Override output safely with template overrides, never by editing core files.
• Escape output, filter input, and bind SQL, because a module renders untrusted data on a public page.

12. Summary

In Joomla, modules are the quiet building blocks around your content. They influence almost every part of the visible page:

• Navigation: the menus and breadcrumbs visitors use.
• Layout: the sidebars, banners, and footer that frame the content.
• Targeting: which pages and which user groups see each block.
• Performance: caching that keeps pages fast without leaking user state.
• Reuse: a clean Dispatcher, Helper, and layout structure you can copy and extend.

Once you understand how one module is assembled, positioned, and assigned, you can place, override, and build any module on the site. When a module refuses to show, the answer is almost always in the five-point checklist: published, position, assignment, access, language.

If you are planning a new Joomla site, building a custom module, or you are stuck with a module that will not appear where you expect, it pays to understand this architecture early. Modules are simple to use, but the details underneath are where good Joomla sites are made.