Banners in Joomla

1. The Basics

1.1 The Three Building Blocks

The whole component rests on three simple concepts. Once you understand how they relate, everything else falls into place.

The relationship is easy to remember: a banner belongs to one category and, optionally, to one client.

1.2 How the Parts Fit Together

Here is the mental model:

Client  ─┐
         ├─ Banner ─ Category
Tracks  ─┘   (creative)   (grouping)

• Banner is the thing visitors actually see.
• Client is who the banner is for, and it holds the default tracking settings.
• Category is how you group banners so a module can pull from them.
• Tracks is the log of impressions and clicks.

1.3 Where to Find It

In the Joomla 6 backend, the component lives under the Components menu:

Components → Banners → Banners      (the creatives)
Components → Banners → Categories   (grouping)
Components → Banners → Clients      (advertisers)
Components → Banners → Tracks       (impression / click log)

The front-end display is handled separately, by a module:

System → Site Modules → New → Banners   (mod_banners)

Remember this split: the component stores and manages the data, the module shows it on the website.

1.4 Two Kinds of Banner

On the banner edit screen, the Type field decides everything else:

With an Image banner, Joomla builds the <a><img></a> markup for you. With a Custom banner, you control the markup completely, which is great for responsive ads or third-party tags. As we will see in section 8, this freedom also comes with a security cost.

3. Displaying Banners with mod_banners

3.1 The Module Is the Delivery Engine

This is the single most important thing to understand: a banner does nothing until a Banners module renders it. The component stores the data, but mod_banners selects and shows it.

Banner (data)  →  mod_banners (selection + render)  →  module position

Create the module under System → Site Modules → New → Banners, then assign it to a position and to the menu items where it should appear.

3.2 Module Options

The module options decide which banners are eligible and how they look:

3.3 Ordering and Rotation

The selection query orders the banners in one of two ways, depending on the Randomise setting:

ORDER BY sticky DESC, ordering        -- "Sticky Ordering"
ORDER BY sticky DESC, RAND()          -- "Sticky, Randomise"

The logic is straightforward:

• Sticky banners always come first.
• Within the same level of stickiness, you choose a fixed order or a random one.
• Count then limits how many of those banners are actually rendered.

3.4 Keyword Targeting in Practice

Keyword targeting lets you show relevant banners per page without creating a separate module for each one. It takes three steps:

1. Set Keywords on the banner, for example joomla, hosting.
2. Enable Search by Keywords on the module.
3. On a page whose meta keywords include hosting, that banner becomes eligible.

One module can then serve different banners on different pages, based on what each page is about.

3.5 Template Overrides

The module ships with a single layout that you can fully override. This is the correct place to change how banners look:

modules/mod_banners/tmpl/default.php                       ← the core layout
templates/your_template/html/mod_banners/default.php       ← your override

Use an override to build things the core layout does not offer:

• Sponsor grids or Bootstrap cards.
• Sliders and carousels.
• Lazy-loaded, responsive <picture> markup.

The principle is the same as everywhere else in Joomla: data and presentation stay separate. You override the view, not the model. One tip: the core layout already emits rel="noopener noreferrer" on new-tab links. Keep that when you override, for security.

3.6 Caching versus Impression Accuracy

This is a subtle but important point. An impression is a dynamic write on every render. Caching, by design, avoids re-rendering. So caching and accurate counting work against each other.

The more aggressively you cache, the more impmade undercounts real views. If you need accurate counts, exclude banner modules from the cache. Otherwise, accept that the counts are a floor, not a total.

5. Security of Custom Banners

5.1 Custom HTML Is Stored Raw

This section deserves its own place because it is the one thing people overlook. Custom HTML banners are stored exactly as you type them. Joomla does not sanitise them.

custombannercode   →  filter="raw"     (in banner.xml)
clickurl           →  filter="url"     (URL-validated)

The click URL is validated, but the markup of a custom banner is not.

5.2 Why This Matters

Because custom code is raw, a banner author who can inject a <script> tag creates stored cross-site scripting (XSS) on every page where the module appears. The consequences are practical:

• Only let trusted user groups create custom banners. Gate it with ACL (see section 6).
• Prefer Image banners for creatives supplied by advertisers.
• Reserve Custom banners for your own staff.

A simple way to remember it: image banners are safe by construction, while custom banners trade safety for control. The redirect validates the destination URL, but the markup is your responsibility.

7. Under the Hood (Developer View)

7.1 Three Tables

The entire component is built on three dedicated tables:

#__banners          the creatives + counters + targeting
#__banner_clients   advertisers + default tracking / purchase
#__banner_tracks    hourly aggregate of clicks / impressions

Plus rows in the shared #__categories table, where extension = com_banners.

7.2 Key Columns in #__banners

The main table carries the creative, the counters, and the targeting all in one place:

type                0 = image, 1 = custom HTML
custombannercode    raw markup for custom banners
params              JSON: imageurl, width, height, alt, ...
cid                 client id  (→ #__banner_clients)
catid               category id (→ #__categories)
imptotal / impmade  impression cap / count
clicks              click count
sticky              float to top of rotation
state               published / unpublished / archived / trashed
metakey             keywords used for targeting
own_prefix / metakey_prefix    custom prefix matching
track_clicks / track_impressions   -1 inherit, 0 off, 1 on
purchase_type       -1 inherit, else billing cycle
reset               when counters reset
language            '' = all, or a language tag

7.3 The MVC Layout

The code is split across three locations, following Joomla's standard structure:

administrator/components/com_banners/   ← manage banners, clients, tracks
   src/Model, src/Table, src/Controller, tmpl/, forms/

components/com_banners/                  ← front-end click + selection
   src/Model/BannersModel.php   (selection + impressions)
   src/Model/BannerModel.php    (single banner + click tracking)
   src/Controller/DisplayController.php

modules/mod_banners/                     ← renders the chosen banners
   src/Helper/BannersHelper.php
   tmpl/default.php

7.4 The Selection Query

BannersModel::getBannerQuery() builds roughly this query to pick eligible banners:

SELECT a.*
FROM #__banners AS a
LEFT JOIN #__banner_clients AS cl ON cl.id = a.cid
LEFT JOIN #__categories     AS cat ON cat.id = a.catid
WHERE a.state = 1
  AND (a.publish_up   IS NULL OR a.publish_up   <= :now)
  AND (a.publish_down IS NULL OR a.publish_down >= :now)
  AND (a.imptotal = 0 OR a.impmade < a.imptotal)
  AND cl.state = 1
  [AND a.catid IN (:categories)]
  [AND keyword/metakey REGEXP conditions]
ORDER BY a.sticky DESC, a.ordering   -- or RAND()

This single query explains most of the behaviour described earlier: state, the publish window, the impression cap, the client state, and the ordering all live here.

7.5 Keyword Matching Is Real SQL

When keyword search is on, Joomla matches each page keyword with a word-boundary regular expression against the banner, client, and category metakeys:

$regexp = $db->getServerType() === 'mysql'
    ? '\\b' . $keyword . '\\b'                 // MySQL / MariaDB
    : '[[:<:]]' . $keyword . '[[:>:]]';        // PostgreSQL

There is also the own-prefix logic: a banner can match a prefix of a keyword rather than the whole word, which allows fine-grained targeting without exact matches.

7.6 Custom Banner Code Tokens

For custom banners, the custombannercode can contain placeholders that mod_banners replaces at render time:

{CLICKURL}   → the tracked click-through URL
{NAME}       → the banner name

This is a neat detail: it lets a hand-written <a> or <script> creative still flow through Joomla's click tracking, so you do not lose your statistics just because you wrote the markup yourself.

7.7 Programmatic Access

The same nested-set Categories API that serves articles also serves banners:

use Joomla\CMS\Categories\Categories;

$categories = Categories::getInstance('Banners');
$node       = $categories->get('sponsors');   // by alias or id
$children   = $node->getChildren();

The table and model classes live under predictable namespaces:

Joomla\Component\Banners\Administrator\Table\BannerTable
Joomla\Component\Banners\Site\Model\BannersModel

7.8 Web Services API (Headless)

The component ships a REST API, so banners and clients are reachable headlessly:

api/components/com_banners/
   src/Controller/BannersController.php
   src/Controller/ClientsController.php
   src/View/Banners, src/View/Clients

GET  /api/index.php/v1/banners
GET  /api/index.php/v1/banners/clients

This opens the door to modern architectures, where the data lives in Joomla but the delivery happens elsewhere:

Joomla API  →  React / Vue front-end  →  custom banner rendering

One caveat: API delivery bypasses mod_banners, so you have to count impressions and clicks yourself.

7.9 Behaviour at Scale

The model is simple, but a few things bite on large installs:

Tracking is designed to stay small through hourly buckets. The main long-term maintenance job is archiving #__banner_tracks.

9. Best Practices

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

• Create the client first, then the banner, then the module that shows it.
• Prefer image banners for advertiser creatives; reserve custom banners for trusted staff.
• Use the impression cap to deliver exactly what a client paid for.
• Exclude banner modules from cache if you need accurate impression counts.
• Use categories to group banners into rotation pools by campaign or sponsor.
• Archive #__banner_tracks periodically on busy sites.

11. Summary

Joomla Banners is a complete, self-hosted ad server hiding in plain sight. Once you see it that way, the component stops looking like a simple image uploader and starts looking like a small, capable system.

It gives you:

• Delivery: rotation, sticky priority, count, and randomisation.
• Targeting: by keyword, category, client, and language.
• Limits: impression caps, scheduling, and billing cycles.
• Analytics: first-party impression and click tracking.
• Integration: the shared Categories tree, ACL, and a clean MVC model.
• Privacy: no external network and no cookies by default.

The data lives in Joomla, but the delivery can live anywhere, from a classic module to a headless React front-end. The one rule to keep in mind throughout is the separation of concerns: the component holds the data, the module renders it, and the template override controls how it looks.

If you are running paid placements, house ads, or sponsor rotations, and you want them counted, capped, and targeted without a third-party network, Joomla Banners already has what you need. The hard part is not the feature set. It is knowing it is there.