Wrapper in Joomla

1. De basis

1.1 Wat een Wrapper is

Een Wrapper is een <iframe> met een Joomla-menu-item ervoor. Als een bezoeker op de menulink klikt, rendert Joomla een normale pagina met jouw template, en in het contentgebied plaatst het een enkel frame dat een ander webadres laadt.

Zie het als een raam. Jouw template is de muur. Het iframe is het raam. Door het raam zie je een compleet aparte webpagina, geserveerd door een ander script of zelfs een andere server.

De Wrapper kopieert, importeert of bewaart de externe pagina niet. Het vertelt de browser alleen: "laad deze andere URL in dit vak."

1.2 Wat het bijzonder maakt

Bijna elk core-component van Joomla slaat iets op: artikelen, contacten, banners, feeds. De Wrapper slaat niets op. Het heeft:

• Geen eigen databasetabel.
• Geen categorieen.
• Geen aangepaste velden.
• Geen beheerscherm waar je "wrapper-records" maakt.
• Geen Web Services (REST) API.

Alles wat een wrapper nodig heeft - de URL, de breedte, de hoogte - staat in de menu-item-parameters. Het menu-item is de wrapper. Verwijder het menu-item en de wrapper is weg.

1.3 Waar je het vindt

Je vindt geen "Wrapper" onder het Componenten-menu, want daar valt niets te beheren. Je maakt een wrapper als een menu-itemtype:

Menu's → (jouw menu) → Nieuw → Iframe Wrapper

In de keuzelijst voor menu-itemtypes staat het onder Wrapper als Iframe Wrapper. Die ene layout is de hele frontend van het component.

3. De Wrapper-opties uitgelegd

Een wrapper-menu-item biedt een kleine, vaste set parameters. Ze zijn gegroepeerd in drie fieldsets in tmpl/wrapper/default.xml.

3.1 Basic (Scroll Bar Parameters)

3.2 Advanced

Let op een naamkundig detail: het label is Auto Add, maar de opgeslagen parameter heet add_scheme. De beschrijving in de backend legt het goed uit: standaard wordt http:// toegevoegd, tenzij Joomla http:// of https:// in de opgegeven URL detecteert.

3.3 Pagina-weergave (overgeerfd)

Zoals elk menu-item heeft een wrapper ook het standaard tabblad Pagina-weergave: Browserpaginatitel, Toon paginakop en Paginakop. De layout gebruikt deze om een optionele <h1> boven het frame te tonen en om het title-attribuut van het iframe te zetten - wat belangrijk is voor toegankelijkheid.

5. Auto Height en het iFrame-script

Een iframe groeit niet mee met zijn inhoud zoals een gewone <div> dat doet. Je geeft het een vaste hoogte, en alles wat hoger is scrollt binnen het frame. Auto Height is Joomla's poging om dat op te lossen.

5.1 Hoe het werkt

Als height_auto aanstaat, voegt de view een onload-handler toe aan het iframe:

<iframe onload="iFrameHeight(this)" ... >

De handler zit in het eigen script van het component, media/com_wrapper/js/iframe-height.js. Simpel gezegd doet het dit:

1. Lees de binnenpagina zodra het frame klaar is met laden.
2. Meet document.body.scrollHeight.
3. Zet de iframe-hoogte op die waarde + 60px (een kleine marge).

Het resultaat is een frame dat hoog genoeg is om de verpakte pagina te tonen zonder interne scrollbalk.

5.2 De grote valkuil: alleen same-origin

iframe.contentDocument.body.scrollHeight lezen betekent in de verpakte pagina reiken. Browsers staan dat alleen toe als de verpakte pagina dezelfde origin heeft (zelfde schema, host en poort) als je Joomla-site.

Dus Auto Height werkt alleen als je een pagina op je eigen domein verpakt. Wijs je naar een ander domein, dan blokkeert het same-origin-beleid van de browser de meting. Het script faalt stilletjes en het frame houdt zijn vaste height.

Vuistregel: Auto Height is voor het verpakken van je eigen oude pagina's. Stel voor externe sites een verstandige vaste hoogte in.

7. Onder de motorkap (ontwikkelaarsblik)

7.1 Geen tabel, geen modeldata

Er is geen #__wrapper-tabel. Het component leest alles uit de parameters van het actieve menu-item:

$params = Factory::getApplication()->getParams();
$url    = $params->def('url', '');

Dat is de hele gegevensbron. Het "model" heeft niets te laden, want de pagina die je ziet staat op een andere server.

7.2 Waar de instellingen echt staan

"Geen eigen tabel" betekent niet "nergens opgeslagen". Een wrapper leunt op twee gedeelde core-tabellen:

De configuratie die je in het menu-item instelt belandt dus als JSON-string in #__menu.params:

SELECT id, title, params
FROM #__menu
WHERE link LIKE '%com_wrapper%';

-- params (gedecodeerd):
-- {"url":"https://example.com","width":"100%","height":"500",
--  "height_auto":"0","add_scheme":"1","lazyloading":"lazy"}

Joomla laadt die JSON in een Registry-object, en dat is precies wat $params->get('url') in de view leest. Daarom verwijdert het verwijderen van het menu-item ook de wrapper: de menuregel is de opslag.

7.3 De MVC-indeling

Het component is een van de kleinste in Joomla:

administrator/components/com_wrapper/      ← registreert het component + de router
   src/Extension/WrapperComponent.php
   services/provider.php

components/com_wrapper/                     ← de hele frontend
   src/Controller/DisplayController.php     forceert caching, zet de view
   src/View/Wrapper/HtmlView.php            bouwt de URL + params
   src/Service/Router.php                   triviale SEF-routing
   tmpl/wrapper/default.php                 print het <iframe>
   tmpl/wrapper/default.xml                 de menu-item-opties

Er is een beheerderskant, maar die bestaat alleen om het component en de router te registreren zodat het menu-itemtype beschikbaar is. Er is geen beheerscherm.

7.4 De controller forceert caching

De display-controller zet caching hard aan:

public function display($cachable = false, $urlparams = [])
{
    $cachable = true;   // altijd cachen
    $vName    = $this->input->get('view', 'wrapper');
    $this->input->set('view', $vName);

    return parent::display($cachable, ['Itemid' => 'INT']);
}

Dat is goedkoop en veilig: de uitvoer is alleen een <iframe>-tag, identiek voor elke bezoeker van dat menu-item. Het dure deel - de verpakte pagina laden - gebeurt in de browser van de bezoeker, niet op jouw server, dus er valt sowieso niets zwaars te cachen.

7.5 De router is bijna leeg

Omdat er maar een view is en geen records, doet de router nauwelijks iets:

public function build(&$query) {
    unset($query['view']);   // niets te coderen
    return [];
}
public function parse(&$segments) {
    return ['view' => 'wrapper'];   // altijd dezelfde view
}

In de praktijk is de SEF-URL simpelweg de alias van het menu-item. Er zijn geen id's, slugs of extra segmenten om te routeren.

7.6 Wat de template print

De uitvoer van de layout is kort. Zonder het kop-blok is het in essentie:

<div class="com-wrapper contentpane">
  <iframe id="blockrandom" name="iframe"
          src="/(de verwerkte URL)"
          width="(width)" height="(height)"
          loading="(lazy|eager)"
          title="(paginakop of titel)"
          class="com-wrapper__iframe wrapper">
    This option will not work correctly. Unfortunately, your
    browser does not support inline frames.
  </iframe>
</div>

De tekst binnen het iframe is de fallback voor browsers die geen frames kunnen renderen - vandaag de dag vrijwel geen enkele, maar het is correcte HTML om die te bieden.

7.7 Template-overrides

Je kunt de layout overriden zoals elke andere view:

components/com_wrapper/tmpl/wrapper/default.php
templates/<jouw_template>/html/com_wrapper/wrapper/default.php   ← override

Dit is de juiste plek om een omhullend element, extra ARIA-attributen, een responsieve aspect-ratio-box of een sandbox-attribuut op het iframe toe te voegen (zie sectie 8).

9. SEO en metadata

Een wrapper-pagina is een van de zwakste pagina's die je voor zoekmachines kunt publiceren, en het helpt te begrijpen waarom.

• Zoekmachines indexeren geframede inhoud niet als de jouwe. De tekst binnen het iframe hoort bij de andere URL. Google schrijft die toe aan die site, niet aan jouw wrapper-pagina.
• Je wrapper-pagina heeft bijna geen eigen tekst - alleen een optionele kop en een frame. Er valt voor een crawler weinig te ranken.
• De view stelt nog steeds metadata in. De browserpaginatitel, meta description en robots uit het tabblad Metadata van het menu-item worden toegepast, dus je kunt op zijn minst de titel en noindex sturen indien nodig.

Is een pagina belangrijk voor SEO, verpak die dan niet - bouw die content na als een echt Joomla-artikel. Reserveer de Wrapper voor tools en hulpmiddelen waar ranking niet uitmaakt: dashboards, rekenmachines, boekingswidgets, interne apps.

11. Best practices

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

• Gebruik de Wrapper voor tools en externe apps, nooit voor content die moet ranken in zoekmachines.
• Verpak altijd HTTPS-URL's om mixed-content-blokkering te voorkomen.
• Verwacht dat Auto Height alleen werkt voor pagina's op je eigen domein; stel anders een vaste hoogte in.
• Controleer voordat je een site verpakt of die framen niet verbiedt met X-Frame-Options of frame-ancestors.
• Stel een duidelijke Paginakop in - die wordt het toegankelijke title-attribuut van het iframe.
• Voeg voor onbetrouwbare doelen een sandbox-attribuut toe via een template-override.
• Heeft de verpakte app een login nodig, verwacht dan cross-domain-cookieproblemen tenzij die SameSite=None; Secure instelt.
• Kies het juiste gereedschap: een volledige pagina gebruikt com_wrapper; een widget in de zijbalk gebruikt mod_wrapper.

13. Samenvatting

De Wrapper is het kleinste core-component in Joomla, en het doet precies een ding: het zet een <iframe> op een pagina en wijst dat naar een URL.

Wat het waard maakt om te begrijpen:

• Geen opslag: er is geen tabel, geen record, geen categorie. De menu-item-parameters zijn de hele configuratie.
• URL herschrijven: Auto Add normaliseert stilletjes je URL en forceert meestal het huidige schema.
• Auto Height: een handige JavaScript-resize die alleen werkt voor same-origin-pagina's.
• Twee frontends: com_wrapper voor een volledige pagina, mod_wrapper voor een modulepositie, met een gedeeld script.
• Beveiliging eerst: of een frame uberhaupt laadt, bepaalt de doelsite met zijn frame-headers, niet Joomla.
• Zwak voor SEO: geframede inhoud telt nooit als de jouwe.

Zodra je ziet dat de Wrapper niets opslaat en simpelweg een URL aan de browser doorgeeft, valt elke eigenaardigheid op zijn plek - het herschreven schema, de stille Auto Height-mislukking, het lege "refused to connect"-frame.

Verpak je een oude tool, een extern boekingssysteem of een interne app en gedraagt het frame zich niet, dan zijn deze frame-headers en same-origin-regels meestal de oorzaak. Wordt een wrapper een hardnekkig integratieprobleem, dan loont het vaak om eerst te kijken hoe de twee sites met elkaar mogen praten voordat je Joomla de schuld geeft.