Modules in Joomla

Modules zijn de kleine blokken rondom de hoofdinhoud van een Joomla-pagina: het menu, het inlogformulier, de broodkruimelnavigatie, de lijst met recente artikelen en de footer.

In de backend lijken ze eenvoudig, maar achter de schermen hebben ze te maken met posities, paginatoewijzingen, toegangsrechten, caching en een overzichtelijke structuur die je zelfs zelf kunt bouwen.

Hoe Joomla de kleine blokken rondom elke pagina opbouwt, plaatst en toewijst.

In dit artikel lees je hoe Joomla-modules echt werken. We beginnen bij de basis voor website-eigenaren en redacteuren, gaan daarna verder met de praktische configuratie voor beheerders en eindigen met de technische details voor ontwikkelaars. Je leert wat een module is, hoe deze op een pagina terechtkomt, hoe je bepaalt waar deze wordt weergegeven en hoe je de meest voorkomende fouten voorkomt.

De belangrijkste gedachte om mee te nemen is deze: een pagina bevat precies één component in het midden, maar zoveel modules als je wilt eromheen. Zodra je begrijpt hoe een module wordt opgebouwd, gepositioneerd en toegewezen, kun je elke module plaatsen, overriden en zelf ontwikkelen.

2. Site- versus administrator-modules

2.1 Twee clients, één concept

Modules bestaan in twee afzonderlijke omgevingen, die van elkaar worden onderscheiden door een waarde genaamd 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 worden weergegeven in de posities van het front-end template.
• Administrator-modules worden weergegeven in het back-end template, bijvoorbeeld op dashboards van het Controlepaneel, in de werkbalk en bij de paginatitel.

Het gaat om dezelfde architectuur en dezelfde bestandsstructuur. Alleen de client en het template waarin de modules worden gebruikt verschillen van elkaar.

2.2 Hoe een module op de pagina terechtkomt

Een module ontvangt nooit zelf de aanvraag. Joomla verzamelt en rendert modules terwijl het template wordt opgebouwd:

Browserverzoek
   │  index.php?option=com_content&view=article&id=42
   ▼
CMS-applicatie → Router → Component wordt uitgevoerd en genereert de hoofdinhoud
   ▼
Template rendert:  <jdoc:include type="component" />   ← uitvoer van het component
                   <jdoc:include type="modules" name="sidebar-right" />
   ▼
Voor elke modulepositie die het template opvraagt:
   ModuleHelper::getModules('sidebar-right')
      → laad gepubliceerde modules voor deze positie
      → filter op toegangsniveau, taal en menu-toewijzing
      → render elke module via zijn Dispatcher + layout
   ▼
Template voegt alles samen → pagina wordt naar de browser gestuurd

De tags <jdoc:include type="modules" name="..."> in het template zijn de aansluitpunten. Modules zijn de onderdelen die je daarop aansluit.

4. Binnenin een module (voor ontwikkelaars)

4.1 De moderne mapstructuur van Joomla 4/5/6

Modules zijn "MVC-light". Er is geen Controller en geen aparte Model-klasse. In plaats daarvan bestaat een module uit een Dispatcher, een Helper en een layout:

modules/mod_articles_latest/
├── mod_articles_latest.xml      ← manifest (naam, versie, bestanden, parameters)
├── services/
│   └── provider.php             ← registratie van DI-services (entry point)
├── src/
│   ├── Dispatcher/
│   │   └── Dispatcher.php       ← bereidt de gegevens voor de layout voor
│   └── Helper/
│       └── ArticlesLatestHelper.php  ← de daadwerkelijke logica en data-opvraging
├── tmpl/
│   └── default.php              ← de HTML-layout
└── language/                    ← vertaalbestanden (.ini)
    └── en-GB/
        ├── mod_articles_latest.ini
        └── mod_articles_latest.sys.ini

Sinds Joomla 4 bestaat er geen mod_xxx.php-bestand meer in de hoofdmap. Het entry point is nu services/provider.php, net zoals bij componenten.

4.2 Het 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"> ... het Opties-formulier van de module ... </fields>
    </config>
</extension>

De belangrijkste attributen zijn:

• type="module" en client="site" (of client="administrator").
• <namespace> registreert PSR-4-autoloading voor de map src/.
• <config><fields name="params"> definieert het formulier dat je ziet in de module-editor. Joomla slaat de resultaten op als JSON in #__modules.params.

4.3 Het entry point (services/provider.php)

Net als componenten registreren modules zichzelf in de Dependency Injection-container (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 maakt de Dispatcher van de module aan.
• HelperFactory maakt Helper-objecten aan, waarbij de database automatisch wordt geïnjecteerd.
• Module() is de generieke moduleservice die alles met elkaar verbindt.

Er zijn geen handmatige require-statements en geen globale variabelen nodig. Het gebruikt dezelfde moderne architectuur als componenten, maar dan lichter.

4.4 De Dispatcher, gegevens voorbereiden

De Dispatcher heeft één taak: de gegevens verzamelen die de layout nodig heeft en deze doorgeven.

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;                      // wordt beschikbaar als variabelen in tmpl/default.php
    }
}

Alle sleutels die je toevoegt aan $data worden beschikbaar als variabelen zoals $list, $params, $module enzovoort binnen de layout.

4.5 De Helper, de logica

De Helper doet het echte werk. In dit voorbeeld haalt deze artikelen op. De databaseverbinding wordt via dependency injection aangeleverd:

class ArticlesLatestHelper implements DatabaseAwareInterface
{
    use DatabaseAwareTrait;

    public function getArticles(Registry $params, SiteApplication $app)
    {
        // Hergebruik het model van het component zelf, bouw de query niet opnieuw:
        $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));
        // ... pas categorie-, sorteer- en auteursfilters toe op basis van $params ...

        return $model->getItems();
    }
}

Een goede module is lichtgewicht: ze gebruikt het model van het component voor de gegevens en richt zich uitsluitend op de presentatie.

4.6 De layout (tmpl/default.php)

Dit is pure presentatie. De variabelen komen rechtstreeks uit de $data-array van de Dispatcher:

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

if (!$list) {
    return;                       // niets te tonen → niets renderen
}
?>
<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>

Een module kan meerdere layouts bevatten in de map tmpl/, bijvoorbeeld default.php en _item.php. Joomla slaat de gekozen layout op in de parameter layout van de module.

6. Werken met modules

6.1 Een module aanmaken en plaatsen

De standaardwerkwijze is als volgt:

1. Ga naar System → Manage → Modules (of Site Modules / Administrator Modules).
2. Klik op Nieuw en kies een module-type (mod_custom, mod_menu, enzovoort).
3. Geef de module een titel en bepaal of Titel tonen is ingeschakeld.
4. Stel de Positie in door een templatepositie te kiezen of in te typen.
5. Configureer de Menu-toewijzing: alle pagina's, geen pagina's, geselecteerde pagina's of alle behalve geselecteerde pagina's.
6. Stel Status, Toegang, Taal en eventueel publicatiedatums in.
7. Configureer de type-specifieke Opties (het params-formulier uit het manifest).
8. Klik op Opslaan. Joomla voegt een nieuw record toe aan #__modules.

6.2 De uitvoer van een module op de juiste manier aanpassen

Pas nooit bestanden van core-modules rechtstreeks aan. Joomla overschrijft deze bij een update. Gebruik in plaats daarvan een template override:

Kopieer: modules/mod_articles_latest/tmpl/default.php
Naar:    templates/<jouw-template>/html/mod_articles_latest/default.php

Overrides blijven behouden na updates en maken het mogelijk om een module volledig anders vorm te geven zonder de originele code aan te passen.

6.3 mod_custom, het Zwitserse zakmes onder de modules

Dit is waarschijnlijk de meest veelzijdige standaardmodule van Joomla: vrije HTML- of tekstinhoud met ondersteuning voor de editor.

• Voeg een promotiebanner, scriptfragment, ingesloten kaart of contactgegevens toe.
• Combineer de module met menu-toewijzingen voor inhoud die alleen op specifieke pagina's zichtbaar moet zijn.
• Schakel Prepare Content in de opties in zodat contentplugins worden uitgevoerd binnen de module, bijvoorbeeld voor shortcodes zoals {loadposition} of de uitvoer van aangepaste velden.

In veel gevallen lost een mod_custom in combinatie met een template override vrijwel elke wens op van het type: "ik wil hier een blok met deze inhoud tonen".

6.4 Een module binnen content laden

Soms wil je een module in een artikel weergeven in plaats van op een vaste positie in de zijbalk of footer:

De shortcodes {load...} worden geleverd door de plugin Content - Load Modules. Deze plugin moet ingeschakeld zijn om ze te kunnen gebruiken.

8. Modules debuggen

8.1 De gereedschapskist voor het debuggen van modules

Wanneer een module zich niet gedraagt zoals verwacht (verkeerde positie, geen uitvoer of verouderde inhoud), werk dan deze controles stap voor stap af:

8.2 De drie tabellen die je moet controleren

-- Is de module gepubliceerd, waar staat hij en voor wie?
SELECT id, title, position, published, access, language
FROM #__modules WHERE module = 'mod_articles_latest';

-- Aan welke pagina's is hij toegewezen? (0=alle, negatief=behalve)
SELECT moduleid, menuid FROM #__modules_menu WHERE moduleid = 42;

-- Is het moduletype zelf ingeschakeld?
SELECT element, enabled FROM #__extensions
WHERE type = 'module' AND element = 'mod_articles_latest';

De klassieke checklist voor een module die niet verschijnt is: gepubliceerd? → juiste positie voor dit template? → toegewezen aan deze pagina? → komt het toegangsniveau overeen met de bezoeker? → komt de taal overeen? In negen van de tien gevallen ligt het probleem bij één van deze vijf punten.

10. Best practices en snelle referentie

Als je maar een paar dingen uit dit artikel onthoudt, laat het dan deze zijn:

• Een module is een klein presentatieblok. Er kunnen er meerdere op één pagina staan en de naam begint altijd met mod_.
• Een module heeft geen eigen URL. De <jdoc:include type="modules">-plaatsen in het template en de gekozen positie bepalen waar de module verschijnt.
• Menu-toewijzingen, toegangsniveau, taal, status en datums bepalen of de module wordt weergegeven.
• Houd modules lichtgewicht: de Dispatcher bereidt gegevens voor, de Helper bevat de logica en de layout genereert de HTML.
• Pas uitvoer veilig aan met template overrides, nooit door corebestanden te wijzigen.
• Escape uitvoer, filter invoer en gebruik gebonden SQL-parameters, omdat modules vaak onbetrouwbare gegevens op openbare pagina's tonen.

12. Samenvatting

In Joomla zijn modules de stille bouwstenen rondom je inhoud. Ze beïnvloeden bijna elk zichtbaar onderdeel van een pagina:

• Navigatie: menu's en broodkruimelpaden die bezoekers gebruiken.
• Lay-out: zijbalken, banners en de footer die de inhoud omringen.
• Gerichte weergave: bepalen welke pagina's en gebruikersgroepen een blok te zien krijgen.
• Prestaties: caching die pagina's snel houdt zonder gebruikersgegevens bloot te stellen.
• Hergebruik: een duidelijke structuur met Dispatcher, Helper en layout die je eenvoudig kunt kopiëren en uitbreiden.

Zodra je begrijpt hoe één module wordt opgebouwd, gepositioneerd en toegewezen, kun je elke module op de website plaatsen, overriden en ontwikkelen. Wanneer een module niet verschijnt, ligt de oorzaak bijna altijd bij de bekende checklist van vijf punten: gepubliceerd, positie, toewijzing, toegangsniveau en taal.

Of je nu een nieuwe Joomla-site bouwt, een eigen module ontwikkelt of worstelt met een module die niet verschijnt waar je hem verwacht, het loont om deze architectuur vroeg te begrijpen. Modules zijn eenvoudig in gebruik, maar de details eronder maken het verschil tussen een gewone website en een goed gebouwde Joomla-site.