ConsentLab / Documentation

ConsentLab — Documentation

Lightweight cookie consent manager for Joomla 5 & 6.

ConsentLab is a focused cookie consent extension that handles GDPR and ePrivacy compliance without the complexity of a full privacy platform. It injects a configurable consent banner, blocks scripts until visitors consent, and logs every decision server-side. No SaaS subscription, no external dependencies, and around 8 KB gzipped on the frontend.

Requirements

  • Joomla 5.0 or later (including Joomla 6)
  • PHP 8.1 or later
  • MySQL 5.7+ or MariaDB 10.3+

Installation

  1. Download the pkg_consentlab-1.0.7.zip package file.
  2. In your Joomla admin panel, go to System > Install > Extensions.
  3. Upload the package file and click Upload & Install.
  4. The installer will set up the component, the system plugin (banner and script blocking), and the content plugin (shortcode).
  5. The consent banner will appear on your frontend immediately after installation.

Getting Started

Cookie Categories

ConsentLab ships with four pre-seeded cookie categories:

  • Strictly Necessary — required, locked on, cannot be rejected by visitors.
  • Analytics — tracking and analytics scripts (e.g. Google Analytics).
  • Marketing — advertising and remarketing scripts.
  • Preferences — functionality cookies (e.g. language, theme preferences).

To manage categories:

  1. Go to Components > ConsentLab > Cookie Categories.
  2. Each category has a Name, Alias (used for script blocking), Description, Cookie Names, and a Required flag. Aliases must be unique.
  3. Click New to add a category, or click an existing one to edit.
  4. Use the ordering handles to arrange categories in the banner.
  5. Publish or unpublish categories to control which appear in the consent banner.

Required categories are displayed with a locked toggle in the banner — visitors can see them but cannot disable them.

Cookie Names is a comma-separated list such as _ga*, _gid. Use * as a wildcard. The names are shown to visitors in the category details, and when a visitor rejects a category — or later withdraws consent — ConsentLab deletes any matching cookies on the current domain and its parent domains. Cookies in required categories are never deleted.

When you publish a new optional category, visitors who consented before it existed are automatically shown the banner again so they can choose.

Banner Positions

Configure the banner position in Components > ConsentLab > Options > Display:

  • Bottom Bar (default) — full-width bar fixed to the bottom of the viewport.
  • Top Bar — full-width bar fixed to the top of the viewport.
  • Corner Left — compact dialog in the bottom-left corner.
  • Corner Right — compact dialog in the bottom-right corner.
  • Centre Modal — centred overlay dialog with a backdrop.

[image — Component Options showing banner position selector]

Display Options

In Components > ConsentLab > Options > Display, you can also configure:

  • Banner Title — heading text displayed in the banner.
  • Show Banner Title — hide the visible heading while retaining it as the banner’s accessible label.
  • Banner Description — body text explaining your cookie usage.
  • Privacy Policy URL — link to your privacy policy page. Displayed as a link in the banner.
  • Show Reject All — show or hide the “Reject All” button. When hidden, visitors must use individual toggles or accept all.
  • Show Category Details — show or hide the expandable category descriptions in the banner.
  • Show Cookie Settings Button — show a small floating button (bottom left or right) once the visitor has made a choice, so they can review or withdraw consent from any page. Recommended unless you link to the preferences from every page another way (e.g. the shortcode in your footer).
  • Consent Expiry (Days) — how long the consent cookie lasts before re-prompting (default: 365 days).
  • Consent Version — increment this number to re-prompt all visitors. Useful when your cookie policy changes.
  • IP Anonymise — truncate IP addresses stored in the consent log (the last octet of IPv4 addresses and the last 80 bits of IPv6 addresses are set to zero).
  • Log Retention (Days) — consent log entries older than this value are removed automatically (0 = keep indefinitely).

Changing Frontend Button Text

Frontend labels use Joomla language constants rather than hard-coded English. To customise a label, go to System > Manage > Language Overrides, select the site language, and create an override for the relevant constant:

  • PLG_SYSTEM_CONSENTLAB_ACCEPT_ALL
  • PLG_SYSTEM_CONSENTLAB_REJECT_ALL
  • PLG_SYSTEM_CONSENTLAB_CUSTOMISE
  • PLG_SYSTEM_CONSENTLAB_SAVE_PREFERENCES
  • PLG_SYSTEM_CONSENTLAB_REVISIT (floating Cookie settings button)

Create overrides separately for each site language on multilingual sites.

Script Blocking

ConsentLab blocks third-party scripts until the visitor consents to the relevant category. The system plugin rewrites tagged scripts before the browser sees them, so they cannot run before a choice is made.

How to Tag Scripts

Add a data-consentlab attribute to any <script> tag with the category alias:

<!-- Google Analytics -- blocked until "analytics" category is accepted -->
<script data-consentlab="analytics" src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>

<!-- Facebook Pixel -- blocked until "marketing" category is accepted -->
<script data-consentlab="marketing">
  fbq('init', '123456789');
  fbq('track', 'PageView');
</script>

<!-- Third-party chat widget -- blocked until "preferences" category is accepted -->
<script data-consentlab="preferences" src="https://chat.example.com/widget.js"></script>

How It Works

  1. The system plugin scans the page output for <script> tags with data-consentlab attributes.
  2. It rewrites their type attribute to text/plain, preventing execution. Every visitor receives the same blocked markup, which keeps pages safe for Joomla’s page cache, LiteSpeed, Cloudflare and other full-page caches.
  3. The frontend JavaScript reads the visitor’s consent and activates the matching scripts in document order, restoring their original type (including type="module"). An external script without async finishes loading before the next tagged script runs, so inline code that depends on it works as expected.
  4. Scripts tagged with a required category’s alias are activated on every page view.
  5. If a visitor withdraws consent for a category, the page reloads so scripts from that category stop running.

Important Notes

  • The data-consentlab value must match the alias of a published cookie category exactly.
  • Inline scripts and external scripts are both supported.
  • Scripts without a data-consentlab attribute are not affected.
  • If you add scripts via Joomla’s addScript() API, you will need to add them as raw <script> tags with the attribute instead, or use a template override.
  • Tagged scripts run after the page has been parsed, so scripts that rely on document.write() are not supported.

[image — Script tag with data-consentlab attribute in source code]

Consent Log

Every time a visitor accepts, rejects, or modifies their consent, the decision is logged server-side.

Viewing the Log

  1. Go to Components > ConsentLab > Consent Log.
  2. The list shows each consent record with: date, action (accepted/rejected/updated), categories accepted, IP address, and user agent.

CSV Export

Click the Export CSV toolbar button to download the full consent log as a CSV file. Useful for compliance audits and record-keeping.

Purging Old Entries

Set Log Retention (Days) in the component options. Expired entries are removed automatically as new consent is logged, and you can remove them immediately with the Purge Expired Entries toolbar button (requires the Delete permission). Only entries older than the configured retention period are removed. A value of 0 disables purging.

[image — Consent Log admin view with action badges and export button]

Shortcode

ConsentLab includes a content plugin that provides a shortcode for embedding a “Manage Cookie Preferences” link anywhere on your site.

Setup

  1. Go to System > Plugins and ensure Content - ConsentLab is enabled (it is enabled by default on install).
  2. In any article or custom HTML module, add the shortcode:

{consentlab manage}

This renders a link that opens the consent preferences dialog when clicked, allowing visitors to review and change their cookie choices at any time.

Usage Tips

  • Place it in your privacy policy page so visitors can update preferences.
  • Add it to a footer module for site-wide access.
  • The link triggers ConsentLab.showPreferences() — no page reload required.
  • The shortcode works in standard articles and in any content that triggers Joomla’s content prepare event.

Style Options

Configure the visual appearance in Components > ConsentLab > Options > Style:

  • Banner Background — background colour for the consent banner.
  • Banner Text — text colour for the banner.
  • Banner Border — border colour for the banner.
  • Accept Button Background — background colour for the Accept / Accept All button.
  • Accept Button Text — text colour for the Accept button.
  • Reject Button Background — background colour for the Reject All button.
  • Reject Button Text — text colour for the Reject button.
  • Toggle Active Colour — colour for the active state of category toggles.
  • Border Radius — Square, Rounded (default), or Pill.

All colours are applied via CSS custom properties, making them easy to override in your template CSS if needed.

[image — Component Options showing Style tab with colour pickers]

Template Overrides

CSS Classes Reference

The banner markup is generated by the system plugin. Style it from your template using the classes below. The Custom Banner Class field under Options > Style adds one or more sanitized classes to the banner container for site-specific styling.

  • .consentlab-backdrop — backdrop overlay (centre modal position)
  • .consentlab-banner — main banner container
  • .consentlab-banner--bottom-bar, --top-bar, --corner-left, --corner-right, --centre-modal — position modifiers
  • .consentlab-banner__inner — inner layout wrapper
  • .consentlab-banner__content — title and description wrapper
  • .consentlab-banner__title — banner title
  • .consentlab-banner__description — banner description (includes the privacy policy link)
  • .consentlab-banner__categories — category toggles panel
  • .consentlab-category — individual category row
  • .consentlab-category__header — category title and toggle row
  • .consentlab-category__title — category name
  • .consentlab-category__expand — category name button that shows or hides the details
  • .consentlab-category__details — details wrapper
  • .consentlab-category__description — category description text
  • .consentlab-category__cookies — cookie names list
  • .consentlab-toggle — toggle switch label
  • .consentlab-toggle__slider — visible toggle slider
  • .consentlab-toggle--locked — locked toggle modifier for required categories
  • .consentlab-banner__actions — button row
  • .consentlab-btn--accept, --reject, --settings, --save — action buttons
  • .consentlab-revisit — floating Cookie settings button (--left / --right modifiers)
  • .consentlab-manage-link — link output by the {consentlab manage} shortcode

CSS Custom Properties

Set via inline style on .consentlab-banner from the Style options, and overridable in your template CSS:

  • --consentlab-bg
  • --consentlab-text
  • --consentlab-border
  • --consentlab-accept-bg
  • --consentlab-accept-text
  • --consentlab-reject-bg
  • --consentlab-reject-text
  • --consentlab-toggle-active
  • --consentlab-radius

JavaScript API

ConsentLab exposes a public API on window.ConsentLab for programmatic interaction:

ConsentLab.showPreferences()

Opens the consent preferences dialog, allowing the visitor to review and change their category choices.

document.querySelector('.manage-cookies').addEventListener('click', function (e) {
    e.preventDefault();
    ConsentLab.showPreferences();
});

ConsentLab.hasConsent(category)

Returns true if the visitor has a current, valid consent that includes the specified category, false otherwise.

if (ConsentLab.hasConsent('analytics')) {
    // Load analytics script
}

ConsentLab.getConsent()

Returns the visitor’s current consent, or null if they have not chosen yet (or must be asked again after a consent version change).

var consent = ConsentLab.getConsent();
// { v: '1', ts: 1760486400, c: ['necessary', 'analytics'], k: [...], id: '...' }
// c = accepted category aliases

ConsentLab.revokeConsent()

Revokes all consent, clears the consent cookie and the cookies of all optional categories, then reloads the page so the banner is shown again.

document.querySelector('.revoke-cookies').addEventListener('click', function (e) {
    e.preventDefault();
    ConsentLab.revokeConsent();
});

Usage Notes

  • The API is available after the ConsentLab script loads. If you need to call it early, wait for the DOMContentLoaded event.
  • hasConsent() accepts the category alias (e.g. 'analytics', 'marketing').
  • Choices made in the banner are applied immediately: newly accepted scripts are activated, and withdrawing a category reloads the page.

Events

ConsentLab dispatches events on document:

  • consentlab:ready — fired once on page load. event.detail.categories is the array of accepted aliases, or null if the visitor has not chosen yet.
  • consentlab:update — fired whenever the visitor makes or changes a choice. event.detail.categories holds the accepted aliases and event.detail.action is accept, reject_all or save.
document.addEventListener('consentlab:update', function (e) {
    if (e.detail.categories.indexOf('analytics') !== -1) {
        // Analytics accepted
    }
});
← Back to ConsentLab