Modules in Joomla

2. Site- versus administrator-modules

2.1 Twee clients, een 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.

De twee clients hebben ook verschillende positienamen, omdat elk template zijn eigen posities definieert. Het standaard back-end template (Atum) biedt deze administrator-posities:

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 meegegeven.
• 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 een 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 Content → Site Modules (of Content → Administrator Modules voor backend-modules). Beide schermen zijn hetzelfde component com_modules, gescheiden door client_id.
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 een van deze vijf punten.

10. SEO en metadata

Een module heeft geen eigen URL en dus geen eigen metatitel, metabeschrijving of canonical tag. Een module verschijnt nooit als aparte pagina in Google. Toch hebben modules op drie concrete manieren invloed op je SEO.

10.1 Modules bepalen mede de gegenereerde HTML

Zoekmachines lezen de volledige HTML van een pagina, inclusief elke module erop. Dat heeft directe gevolgen:

• Volgorde van koppen: een module die een <h2> of <h3> als titel toont, staat in dezelfde koppenstructuur als het artikel. Te veel modulekoppen kunnen de echte <h1> en de inhoudsstructuur van de pagina overschaduwen.
• Herhaalde blokken: dezelfde module met "recente artikelen" of "populaire tags" op elke pagina herhaalt site-breed dezelfde links. Voor navigatie is dat prima, maar plaats geen grote lappen tekst in een module die overal verschijnt.
• Volgorde in de broncode: een zware zijbalkmodule die voor het component in de HTML-broncode staat, kan de hoofdinhoud naar beneden duwen. Houd de uitvoer van <jdoc:include type="component"> hoog in de broncode waar het template dat toelaat.

10.2 Prestaties zijn onderdeel van SEO

Core Web Vitals zijn een rankingsignaal en modules zijn een veelvoorkomende oorzaak van trage pagina's:

• Een module die een extern script laadt (sociale feed, chatwidget, kaart) kan het renderen blokkeren. Gebruik menu-toewijzing zodat de module alleen laadt op de pagina's die hem nodig hebben.
• Cache stabiele modules (zie hoofdstuk 7) zodat Joomla ze niet bij elk verzoek opnieuw opbouwt.
• Verwijder modules die je niet meer gebruikt in plaats van ze op "Geen pagina's" te laten staan. Een ongebruikte maar gepubliceerde module kost nog steeds werk bij het renderen.

10.3 Gestructureerde data en titels

Als je gestructureerde data (JSON-LD) of een kop toevoegt via een mod_custom-module, houd die dan geldig en uniek op de pagina. Zet Titel tonen uit wanneer een module puur decoratief is, zodat je geen lege of dubbele kop in de koppenstructuur van de pagina injecteert.

12. Best practices

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 een 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.

14. Samenvatting

In Joomla zijn modules de stille bouwstenen rondom je inhoud. Ze raken 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 hergebruiken en uitbreiden.

Zodra je begrijpt hoe 1 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.