Wrapper in Joomla

1. The Basics

1.1 What a Wrapper Is

A Wrapper is an <iframe> with a Joomla menu item in front of it. When a visitor clicks the menu link, Joomla renders a normal page with your template, and inside the content area it drops a single frame that loads another web address.

Think of it as a window. Your template is the wall. The iframe is the window. Through the window you see a completely separate web page, served by another script or another server entirely.

The Wrapper does not copy, import, or store the external page. It only tells the browser: "load this other URL inside this box."

1.2 What Makes It Unusual

Almost every core Joomla component stores something: articles, contacts, banners, feeds. The Wrapper stores nothing. It has:

• No database table of its own.
• No categories.
• No custom fields.
• No back-end management screen where you create "wrapper records".
• No Web Services (REST) API.

Everything a wrapper needs - the URL, the width, the height - lives in the menu item parameters. The menu item is the wrapper. Delete the menu item and the wrapper is gone.

1.3 Where to Find It

You will not find a "Wrapper" entry under the Components menu, because there is nothing to manage there. You create a wrapper as a menu item type:

Menus → (your menu) → New → Iframe Wrapper

In the menu item type chooser it appears under Wrapper as Iframe Wrapper. That single layout is the whole front end of the component.

3. The Wrapper Options Explained

A wrapper menu item exposes a small, fixed set of parameters. They are grouped into three fieldsets in tmpl/wrapper/default.xml.

3.1 Basic (Scroll Bar Parameters)

3.2 Advanced

Note one naming quirk: the label is Auto Add, but the stored parameter is add_scheme. The description in the back end explains it well: "By default, http:// will be added unless it detects http:// or https:// in the URL you provide."

3.3 Page Display (Inherited)

Like every menu item, a wrapper also has the standard Page Display tab: Browser Page Title, Show Page Heading, and Page Heading. The layout uses these to print an optional <h1> above the frame and to set the iframe's title attribute - which matters for accessibility.

5. Auto Height and the iFrame Script

An iframe does not grow to fit its content the way a normal <div> does. You give it a fixed height, and anything taller scrolls inside the frame. Auto Height is Joomla's attempt to fix that.

5.1 How It Works

When height_auto is on, the view adds an onload handler to the iframe:

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

The handler ships in the component's own script, media/com_wrapper/js/iframe-height.js. In plain terms it does this:

1. When the frame finishes loading, read the inner page.
2. Measure document.body.scrollHeight.
3. Set the iframe height to that value + 60px (a small buffer).

The result is a frame that is tall enough to show the wrapped page without an inner scrollbar.

5.2 The Big Catch: Same-Origin Only

Reading iframe.contentDocument.body.scrollHeight means reaching inside the framed page. Browsers only allow that when the framed page is on the same origin (same scheme, host, and port) as your Joomla site.

So Auto Height works only when you wrap a page on your own domain. Point it at a different domain and the browser's same-origin policy blocks the measurement. The script fails silently and the frame keeps its fixed height.

Rule of thumb: Auto Height is for wrapping your own legacy pages. For third-party sites, set a sensible fixed height instead.

7. Under the Hood (Developer View)

7.1 No Table, No Model Data

There is no #__wrapper table. The component reads everything from the active menu item's parameters:

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

That is the entire data source. The "model" has nothing to load, because the page you see lives on another server.

7.2 Where the Settings Actually Live

"No table of its own" does not mean "stored nowhere". A wrapper relies on two shared core tables:

So the configuration you set in the menu item ends up as a JSON string in #__menu.params:

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

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

Joomla loads that JSON into a Registry object, which is exactly what $params->get('url') reads in the view. This is why deleting the menu item deletes the wrapper: the menu row is the storage.

7.3 The MVC Layout

The component is one of the smallest in Joomla:

administrator/components/com_wrapper/      ← registers the component + router
   src/Extension/WrapperComponent.php
   services/provider.php

components/com_wrapper/                     ← the entire front end
   src/Controller/DisplayController.php     forces caching, sets view
   src/View/Wrapper/HtmlView.php            builds the URL + params
   src/Service/Router.php                   trivial SEF routing
   tmpl/wrapper/default.php                 prints the <iframe>
   tmpl/wrapper/default.xml                 the menu item options

There is an administrator side, but it exists only to register the component and its router so the menu item type is available. It has no management view.

7.4 The Controller Forces Caching

The display controller hard-codes caching on:

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

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

This is cheap and safe: the output is just an <iframe> tag, identical for every visitor of that menu item. The expensive part - loading the framed page - happens in the visitor's browser, not on your server, so there is nothing heavy to cache anyway.

7.5 The Router Is Almost Empty

Because there is only one view and no records, the router barely does anything:

public function build(&$query) {
    unset($query['view']);   // nothing to encode
    return [];
}
public function parse(&$segments) {
    return ['view' => 'wrapper'];   // always the same view
}

In practice the SEF URL is simply the menu item alias. There are no ids, slugs, or extra segments to route.

7.6 What the Template Prints

The layout output is short. Stripped of the heading block, it is essentially:

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

The text inside the iframe is the fallback for browsers that cannot render frames - practically none today, but it is valid HTML to provide it.

7.7 Template Overrides

You can override the layout like any other view:

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

This is the right place to add a wrapping element, extra ARIA attributes, a responsive aspect-ratio box, or a sandbox attribute on the iframe (see section 8).

9. SEO and Metadata

A wrapper page is one of the weakest pages you can publish for search, and it helps to understand why.

• Search engines do not index framed content as yours. The text inside the iframe belongs to the other URL. Google credits it to that site, not to your wrapper page.
• Your wrapper page has almost no text of its own - just an optional heading and a frame. There is little for a crawler to rank.
• The view still sets metadata. The Browser Page Title, meta description, and robots from the menu item's Metadata tab are applied, so you can at least control the title and noindex if needed.

If a page matters for SEO, do not wrap it - rebuild that content as a real Joomla article. Reserve the Wrapper for tools and utilities where ranking is irrelevant: dashboards, calculators, booking widgets, internal apps.

11. Best Practices

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

• Use the Wrapper for tools and external apps, never for content that must rank in search.
• Always wrap HTTPS URLs to avoid mixed-content blocking.
• Expect Auto Height to work only for pages on your own domain; otherwise set a fixed height.
• Before wrapping a site, check that it does not forbid framing with X-Frame-Options or frame-ancestors.
• Set a clear Page Heading - it becomes the iframe's accessible title.
• For untrusted targets, add a sandbox attribute via a template override.
• If the wrapped app needs a login, expect cross-domain cookie problems unless it sets SameSite=None; Secure.
• Pick the right tool: a full page uses com_wrapper; a sidebar widget uses mod_wrapper.

13. Summary

The Wrapper is the smallest core component in Joomla, and it does exactly one thing: it puts an <iframe> on a page and points it at a URL.

What makes it worth understanding:

• No storage: there is no table, no record, no category. The menu item parameters are the whole configuration.
• URL rewriting: Auto Add quietly normalises your URL and usually forces the current scheme.
• Auto Height: a handy JavaScript resize that only works for same-origin pages.
• Two front ends: com_wrapper for a full page, mod_wrapper for a module position, sharing one script.
• Security first: whether a frame loads at all is decided by the target site's framing headers, not by Joomla.
• Weak for SEO: framed content is never counted as your own.

Once you see that the Wrapper stores nothing and simply hands a URL to the browser, every quirk - the rewritten scheme, the silent Auto Height failure, the blank "refused to connect" frame - makes sense.

If you are wrapping a legacy tool, an external booking system, or an internal app and the frame will not behave, these framing headers and same-origin rules are usually the cause. When a wrapper turns into a stubborn integration problem, it often pays to look at how the two sites are allowed to talk to each other before blaming Joomla.