AJAX in Joomla

1. De Basis

1.1 Wat is com_ajax?

De naam "Ajax" staat voor een oud idee: een pagina vraagt op de achtergrond een klein stukje data aan de server en werkt zichzelf vervolgens bij zonder een volledige herlaadbeurt. com_ajax is het kerncomponent dat dit eenvoudig maakt in Joomla.

Het is ongebruikelijk onder de Joomla-componenten, want het heeft bijna geen eigen code. Het bouwt geen pagina, het heeft geen menu-items en het heeft geen views. Zijn enige taak is een binnenkomend verzoek aannemen, dat doorgeven aan de juiste extensie, en teruggeven wat die extensie produceert.

Zie com_ajax als een telefoniste: het beantwoordt je vraag niet zelf, het verbindt je oproep alleen door met de juiste extensie en geeft het antwoord terug.

1.2 Welk Probleem Het Oplost

Voor com_ajax moest elke ontwikkelaar die een klein JSON-antwoord wilde, een volledig component bouwen met een controller, een model en een router, alleen om een enkele waarde terug te geven. Dat is veel werk voor een getal.

com_ajax neemt dat werk weg. Een plugin, een module of een template kan een enkele methode aanbieden, en com_ajax roept die aan. Jij schrijft de logica, Joomla regelt het verzoek, de routing en het antwoordformaat.

Als je dit eenmaal hebt, worden veel veelvoorkomende functies eenvoudig:

• Live zoeken en zoeksuggesties terwijl de gebruiker typt.
• Afhankelijke velden - kies een land, en de lijst met provincies wordt bijgewerkt.
• Lazy loading - laad zware inhoud pas wanneer die in beeld scrolt.
• Opslaan zonder herladen - een instelling, een stem, een klik op "herinner me later".
• Dashboard-widgets die elk hun eigen data ophalen.

1.3 De Anatomie van de URL

Elke aanroep van com_ajax is gewoon een URL met een paar query-parameters. Dit is de vorm van een typisch verzoek:

index.php?option=com_ajax&plugin=hello&group=ajax&format=json
          |               |            |           |
          |               |            |           └─ antwoordformaat (verplicht)
          |               |            └─ welke plugin-groep laden
          |               └─ welk doel aanroepen
          └─ altijd com_ajax

Hetzelfde component is bereikbaar vanaf de voorkant (index.php) en vanaf de achterkant (administrator/index.php). De achterkant-versie laadt simpelweg het bestand van de voorkant in.

3. Plugins: Het Meest Gekozen Doel

Voor de meeste projecten is een Ajax-plugin het juiste gereedschap. Een plugin is niet gebonden aan een enkele module of template, dus je kunt hem overal op de site aanroepen.

3.1 Het Event onAjax<Naam>

Wanneer je index.php?option=com_ajax&plugin=hello&format=json aanroept, doet com_ajax twee dingen:

1. Het laadt elke plugin in de gevraagde groep (standaard ajax; overschrijf dit met &group=system en dergelijke).
2. Het vuurt het event onAjaxHello af - het woord na plugin=, met een hoofdletter, met onAjax ervoor.

plugin=hello   ──→   event onAjaxHello
plugin=stats   ──→   event onAjaxStats
plugin=cart    ──→   event onAjaxCart

Elke ingeschakelde plugin die zich op dat event abonneert, wordt uitgevoerd. Dit is hetzelfde publiceer-en-abonneer-model dat alle Joomla-plugins aandrijft.

3.2 Het AjaxEvent-Object

Sinds Joomla 5 geeft com_ajax een getypeerd event-object, AjaxEvent, door aan je methode. Het event draagt altijd de applicatie als subject mee, en het verzamelt wat je teruggeeft in een result-argument.

// In com_ajax, vereenvoudigd:
$eventName = 'onAjax' . ucfirst($input->get('plugin', ''));
$results   = $dispatcher
    ->dispatch($eventName, new AjaxEvent($eventName, ['subject' => $app]))
    ->getArgument('result', []);

Je plugin leest het verzoek, doet zijn werk en voegt zijn antwoord toe aan het resultaat van het event. com_ajax maakt dat resultaat vervolgens op en stuurt het terug.

3.3 Een Volledig Voorbeeld van een Plugin

Hier is een minimale, moderne Ajax-plugin. Hij staat in plugins/ajax/hello/ en antwoordt met een begroeting:

use Joomla\CMS\Event\Plugin\AjaxEvent;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;

final class Hello extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onAjaxHello' => 'onAjaxHello'];
    }

    public function onAjaxHello(AjaxEvent $event): void
    {
        $app  = $event->getApplication();
        $name = $app->getInput()->getString('name', 'world');

        // Voeg het antwoord toe aan het resultaat van het event:
        $event->addResult(['greeting' => 'Hello, ' . $name . '!']);
    }
}

Schakel de plugin in en bezoek dan:

index.php?option=com_ajax&plugin=hello&format=json&name=JUG

Je krijgt een JSON-envelop terug waarvan de data je begroeting bevat.

3.4 Het Resultaat Teruggeven

Het AjaxEvent-object geeft je drie heldere manieren om het antwoord in te stellen:

Gebruik addResult() wanneer meerdere plugins hetzelfde event kunnen beantwoorden, en updateEventResult() wanneer jouw plugin het hele antwoord bezit.

5. com_ajax Aanroepen vanuit de Browser

Tot nu toe hebben we naar de serverkant gekeken. Laten we nu het endpoint aanroepen vanuit JavaScript, want daar wordt com_ajax normaal gesproken voor gebruikt.

5.1 Een Eenvoudige Fetch-Aanroep

De moderne manier is de ingebouwde fetch van de browser. Kern-plugins van Joomla gebruiken precies dit patroon:

const url = 'index.php?option=com_ajax&plugin=hello&format=json&name=JUG';

fetch(url, { method: 'GET' })
  .then((response) => response.json())
  .then((data) => {
    console.log(data.data); // je resultaat zit in .data
  });

Joomla levert ook een kleine helper, Joomla.request(), die het beveiligingstoken automatisch toevoegt. Je kunt de opties uitlezen met Joomla.getOptions('system.paths') om een correcte root-URL op te bouwen.

5.2 Het CSRF-Token en POST-Verzoeken

Een alleen-lezen GET-verzoek is prima om data op te halen. Maar elke aanroep die iets verandert - opslaan, verwijderen, versturen - moet beschermd worden tegen cross-site request forgery (CSRF). Joomla verwacht een eenmalig token.

const token = Joomla.getOptions('csrf.token', '');

fetch('index.php?option=com_ajax&plugin=cart&format=json', {
  method: 'POST',
  headers: { 'X-CSRF-Token': token },
  body: new URLSearchParams({ productId: 42 }),
});

Controleer aan de serverkant het token met Session::checkToken() voordat je op een schrijfverzoek reageert. Vertrouw nooit op een GET-verzoek om data te wijzigen.

5.3 Parameters Doorgeven

Alles wat je aan de URL of de POST-body toevoegt, is beschikbaar via de applicatie-input, precies zoals in alle andere Joomla-code:

$input = $event->getApplication()->getInput();
$id    = $input->getInt('id');          // veilig geheel getal
$name  = $input->getString('name');     // gefilterde string
$html  = $input->get('body', '', 'raw'); // raw, voorzichtig gebruiken

Gebruik altijd de getypeerde getters (getInt, getString, getWord). Ze filteren de invoer voor je en voorkomen veel injectieproblemen.

5.4 Controleer Rechten op de Server

Invoer filteren is niet hetzelfde als controleren wie iets mag doen. Een endpoint aan de voorkant kan door iedereen aangeroepen worden, dus jouw methode moet de rechten van de gebruiker zelf verifieren, met de ACL van Joomla:

$user = $event->getApplication()->getIdentity();

if (!$user->authorise('core.edit', 'com_inventory')) {
    throw new \RuntimeException('Not allowed', 403);
}

Vertrouw nooit op de URL of een verborgen formulierveld om toegang te bepalen. De regel is simpel: filter elke invoer, en autoriseer elke actie.

7. Beveiliging en de Achterkant

Een open endpoint dat data teruggeeft, is een beveiligingsoppervlak. com_ajax heeft meerdere ingebouwde beschermingen, en Joomla 6 voegt een belangrijke nieuwe toe voor de achterkant.

7.1 Voorkant versus Achterkant

Er zijn twee toegangspunten:

• index.php?option=com_ajax&... - de publieke voorkant.
• administrator/index.php?option=com_ajax&... - de achterkant. Het admin-bestand laadt simpelweg het site-bestand in, dus de logica wordt gedeeld.

Aan de voorkant kan iedereen een endpoint aanroepen, dus jouw plugin moet de rechten zelf controleren. Aan de achterkant vereist com_ajax normaal gesproken een ingelogde beheerder.

7.2 Het Attribuut AllowUnauthorizedAdministratorAccess

Soms moet een Ajax-aanroep aan de achterkant draaien voordat de beheerder is ingelogd - bijvoorbeeld een wachtwoordloze login-uitdaging of een captcha-controle op het inlogscherm. Joomla 6 (geintroduceerd in 5.4.4) regelt dit met een PHP-attribuut.

Als een gast com_ajax aan de achterkant aanroept, inspecteert com_ajax de doelmethode. Tenzij die methode met het attribuut is gemarkeerd, weigert het de aanroep met een "niet geautoriseerd"-fout.

use Joomla\CMS\Plugin\Attribute\AllowUnauthorizedAdministratorAccess;

#[AllowUnauthorizedAdministratorAccess]
public function onAjaxMyLoginStep(AjaxEvent $event): void
{
    // Dit mag draaien voor een gast in het beheergedeelte,
    // omdat het attribuut dit expliciet toestaat.
}

Dit is een bewust "standaard weigeren"-ontwerp: een endpoint aan de achterkant is gesloten voor gasten, tenzij je het openstelt, een methode tegelijk.

7.3 Caching en Indexering

com_ajax beschermt zichzelf op elk verzoek op twee extra manieren:

• Het roept allowCache(false) aan, zodat antwoorden nooit uit de paginacache geserveerd worden. Elke aanroep draait vers.
• Het stelt de header X-Robots-Tag: noindex, nofollow in, zodat zoekmachines de endpoint-URL's niet indexeren.

9. Prestaties en Caching

com_ajax is handig, maar het is niet gratis. Weten wat elke aanroep echt kost, helpt je een interactieve pagina snel te houden.

9.1 Elke Aanroep Is een Volledige Joomla-Boot

Een Ajax-verzoek is geen lichtgewicht microservice-aanroep. Elke aanroep start de hele Joomla-stack op voordat jouw methode draait:

Verzoek
   │
   v
Framework + autoloader
   │
   v
Applicatie + DI-container
   │
   v
Sessie + gebruiker
   │
   v
Taalbestanden
   │
   v
Plugins geladen
   │
   v
Jouw Ajax-handler
   │
   v
JsonResponse

Het werk om "wat is de voorraad van item 42?" te beantwoorden omvat al die opstart. Behandel Ajax-aanroepen dus als echte verzoeken: doe er minder, en geef meer per aanroep terug in plaats van veel kleine af te vuren.

9.2 Houd de Handler Dun

Een Ajax-methode moet drie dingen doen: de invoer lezen en controleren, je logica aanroepen, en het resultaat teruggeven. Houd het echte werk in een aparte service- of helper-klasse, niet in de handler zelf.

public function onAjaxInventory(AjaxEvent $event): void
{
    $app = $event->getApplication();
    $id  = $app->getInput()->getInt('id');

    // De handler blijft dun; de service doet het werk.
    $event->addResult($this->inventory->getStock($id));
}

Een dunne handler is makkelijker te testen, makkelijker te lezen, en later makkelijker te hergebruiken vanuit een gewone controller.

9.3 Cache Dure Resultaten

com_ajax schakelt de paginacache uit voor zijn eigen antwoorden, maar niets weerhoudt je ervan de data die je handler produceert te cachen. Waarden die zelden veranderen zijn ideaal:

• Categorieboomstructuren en menu's.
• Lijsten met landen, regio's en valuta's.
• Productcatalogi en zoeksuggesties.

Gebruik de cache van Joomla voor deze opzoekingen, zodat een populair endpoint niet bij elke toetsaanslag de database raakt. Aan de browserkant: debounce snelle gebeurtenissen zoals typen, zodat je een verzoek na een korte pauze stuurt in plaats van een per teken.

11. SEO en Metadata

com_ajax is geen inhouds-URL, en je moet het zich nooit als zodanig laten gedragen.

• com_ajax stuurt al X-Robots-Tag: noindex, nofollow, dus de URL's blijven uit de zoekresultaten. Maak dit niet ongedaan.
• Maak geen menu-items die naar com_ajax wijzen. Het heeft geen leesbare view, dus het zou een kapotte pagina opleveren.
• Houd Ajax-antwoorden klein en alleen-data. Ze zijn voor scripts, niet voor zoekrobots.
• Als een Ajax-antwoord een deel van een pagina opbouwt, zorg er dan voor dat de pagina ook zonder JavaScript werkt, zodat zoekmachines de kerninhoud nog steeds zien.

Kort gezegd: com_ajax serveert data aan de browser, terwijl je normale pagina's inhoud serveren aan mensen en zoekmachines. Houd die twee taken gescheiden.

13. Best Practices

Als je maar een paar dingen uit dit artikel onthoudt, onthoud dan deze:

• Stuur altijd een format. com_ajax raadt er geen voor je.
• Geef de voorkeur aan een Ajax-plugin voor herbruikbare logica; gebruik een module- of template-helper alleen wanneer de logica daar duidelijk thuishoort.
• Gebruik format=json voor data en lees die uit het veld data; gebruik format=raw voor HTML-fragmenten.
• Stuur en verifieer een CSRF-token voor alles wat data wijzigt; houd GET-verzoeken alleen-lezen.
• Filter alle invoer met de getypeerde getters, en autoriseer elke actie met de ACL van Joomla.
• Houd de handler dun: lees invoer, roep een service aan, geef het resultaat terug. Zet de echte logica in een eigen klasse.
• Onthoud dat elke aanroep een volledige Joomla-boot is. Doe minder, grotere aanroepen, en cache resultaten die zelden veranderen.
• Gooi uitzonderingen om fouten te melden; gebruik nooit die() of exit() in een handler.
• Houd endpoints aan de achterkant gesloten voor gasten; stel een methode alleen open voor gasten met het attribuut, wanneer dat echt nodig is.
• Gebruik com_ajax voor interacties binnen de pagina, en de Web Services API voor externe integraties.

15. Samenvatting

com_ajax is een van de kleinste componenten in Joomla, en toch ontsluit het een grote hoeveelheid interactiviteit. In plaats van een volledig component te bouwen alleen om een waarde terug te geven, bied je een enkele methode aan en laat je Joomla het verzoek, de routing en het antwoord afhandelen.

De kerngedachten zijn kort:

• Een endpoint, option=com_ajax, stuurt naar een plugin, een module of een template.
• Plugins beantwoorden het event onAjax<Naam> via een getypeerd AjaxEvent; modules en templates antwoorden met een <method>Ajax()-helper.
• Een format is altijd verplicht, en JSON-antwoorden volgen een vaste envelop.
• Beveiliging staat voorop: filter invoer, gebruik het CSRF-token voor schrijfacties, en houd endpoints aan de achterkant gesloten voor gasten, tenzij je ze bewust openstelt.

Als je live zoeken, een opslaan-zonder-herladen-knop of een kleine datafeed aan je site toevoegt, is com_ajax meestal de schoonste manier om dat te doen. En als je hulp nodig hebt bij het ontwerpen van een veilig Ajax-endpoint, bij het uitzoeken waarom er niets terugkomt, of bij de keuze tussen com_ajax en de Web Services API, dan is dat precies het soort geavanceerde Joomla-werk dat ik dagelijks doe.