Documentation

5.0.3 Overview

System - EU e-Privacy Directive is a Joomla 5 plugin designed to manage user consent for privacy-related features, aligning with the EU e-Privacy Directive’s implied consent approach. It replaces its predecessor with a single-plugin solution—no modules needed—offering a clean, customizable interface and granular control over services like analytics and tracking.

Requirements

• Joomla 5.x  
• PHP 8.1+ (Joomla 5 standard)  
• Bootstrap 5 (included with Joomla 5 for styling)

Installation

1. Download: Get the latest version from RicheyWeb.com—avoid third-party sources to ensure authenticity.  
2. Install:  
   • Log in to your Joomla Administrator panel.  
   • Go to System > Extensions > Install Extensions.  
   • Upload the plugin ZIP file via the “Upload Package File” tab.
3. Enable:  
   • Navigate to System > Manage > Plugins.  
   • Search for “System - EU e-Privacy Directive”.  
   • Click the red “X” or toggle to enable it (turns green).

Configuration

Basic Setup

1. Open Plugin Settings:  
   • In the Plugins list, click “System - EU e-Privacy Directive”.
2. Key Options:  
   • Display Type: Choose how the consent UI appears:  
     • BS5 Alert: Inline banner (default).  
     • BS5 Modal: Pop-up dialog.

And that's it.  Super easy, barely an inconvenience.

Settings to control individual consents are handled in the plugins that the consents control.  At the time of this writing, there are 3 RicheyWeb system plugins designed to directly (and automatically) integrate with System - EU e-Privacy Directive.  Those extensions are:

• System - Google Tag Manager
  • Handling GA4 integration, with built-in consent settings for all currently documented consent types offered by Google.
• System - Global Privacy Control
  • Handling the SEC-GPC header sent by some browsers.
• System - Do Not Track
  • Handling the DNT header sent by some browsers.

Each of the integrated plugins sends its own consent configurations to System - EU e-Privacy Directive.  In the case of Google Tag Manager, a change to consent immediately fires the gtag() function to alter consent for the user session.

Advanced Configuration

• Custom Strings: Override default text (e.g., “We Value Your Privacy”) via Joomla’s Language Overrides:  
  
  • System > Manage > Language Overrides
  • PLG_SYSTEM_EPRIVACY_TITLE="We Value Your Privacy"
  • PLG_SYSTEM_EPRIVACY_MESSAGE="We use cookies to enhance your experience and for traffic analysis. By continuing to visit this site you agree to our use of cookies."
• Styling:
  • Adjust the BS5 Modal using a template override in your template directory/html/plg_system_eprivacy/modal.php
  • Adjust the BS5 Alert using CSS variables in your template
    • #plg_system_eprivacy_alert { --bg-color: black; -color: white; } /* changes the background to black, and the text to white */
• Cookies: No manual config—handled automatically (see Operation).

Operation

How It Works

• On Page Load:  
  • Checks for a plg_system_eprivacy cookie:  
    • No Cookie: First visit—UI opens (Alert or Modal, per setting).  
    • Cookie = 1: User accepted—UI skips, services use plugin cookies (e.g., plg_system_gtag).  
    • Cookie = 0: User declined non-mandatory—UI skips, only mandatory options apply.
• User Interaction:  
  • Accept: Sets plg_system_eprivacy=1, saves plugin cookies, triggers service functions.  
  • Decline: Sets plg_system_eprivacy=0, sets non-mandatory to 'denied' in plugin cookies.  
  • Details: Accordion shows service groups (e.g., plg_system_gtag) with checkboxes—mandatory locked, others toggleable.
• Revisiting:  
  • Clicking any link with a .plg_system_eprivacy_privacy class reopens the UI, resetting all options to checked (mandatory locked), ignoring prior choices.
  • Put the link anywhere, in your template, in a module, in a menu item - if it's on the page when the page loads, it'll open the Alert/Modal.
  • Or don't put any link on your page and let your users keep whatever initial settings they chose.
• Agree or Decline:
  • Regardless of what they select, a window event fires to let you integrate further.  Just listen for these events:
    • plg_system_eprivacy_accepted
    • plg_system_eprivacy_declined

Cookies

• Master Cookie: plg_system_eprivacy  
  • 1: Accepted all or custom settings.  
  • 0: Declined non-mandatory options.
• Plugin Cookies: Named after plugins (e.g., plg_system_gtag, plg_system_donottrack):  
  • JSON object, e.g., {"analytics_storage": "granted", "ad_user_data": "denied"}.  
  • Updated on Accept/Decline; mandatory items always 'granted'.

Interface Details

• Title: “We Value Your Privacy”.  
• Text: “We use cookies to enhance your experience and for traffic analysis. By continuing to visit this site you agree to our use of cookies.”  
• Buttons: Green “Accept”, Red “Decline”.  
• Accordion: “Details” reveals:  
  • Groups by plugin (e.g., plg_system_gtag).  
  • Checkboxes with tooltips (e.g., “Tracks site usage”).  
  • Mandatory options checked/disabled.
• Reset: Revisits show all options checked, encouraging consent.

Integration Interface

Overview

plg_system_eprivacy allows other plugins to register consent options, making it extensible for services like Google Analytics (gtag), Do Not Track, or custom tools. Participating plugins hook in via Joomla’s script options system.

How to Integrate

Register Options: In your plugin’s PHP (e.g., plg_system_gtag):  

use Joomla\CMS\Factory;
$doc = Factory::getApplication()->getDocument();
$options = (object)[
    'analytics_storage' => 'granted', // Mandatory example
    'ad_user_data' => 'denied'
];
$scriptOptions = $doc->getScriptOptions('plg_system_eprivacy', []);
$scriptOptions['plg_system_gtag'] = [
    'function' => 'gtag', // JS function to call
    'consent' => $options,
    'mandatory' => ['analytics_storage'] // Locked options
];
$doc->addScriptOptions('plg_system_eprivacy', $scriptOptions);

Add Translations: Define strings in your plugin’s language file (e.g., plg_system_gtag.ini):  

PLG_SYSTEM_GTAG_ANALYTICS_STORAGE="Allow Analytics?"
PLG_SYSTEM_GTAG_ANALYTICS_STORAGE_DESC="Tracks site usage for analytics."

Within your plugin, load them with Text::script():  

Text::script('PLG_SYSTEM_GTAG_ANALYTICS_STORAGE');
Text::script('PLG_SYSTEM_GTAG_ANALYTICS_STORAGE_DESC');

Result:  

• plg_system_eprivacy picks up plg_system_gtag, shows “Allow Analytics?” in the UI (checked, disabled), with a tooltip “Tracks site usage…”.  
• On save, it sets plg_system_gtag cookie and calls gtag('consent', 'update', {...}).

Notes

• Function: At this time, plg_system_eprivacy cannot execute any other function than gtag().  This will likely change as other developers adopt this system.  
• Cookie: Matches plugin name (e.g., plg_system_gtag).  
• Support: Contact RicheyWeb for integration help or to request built-in services.

Troubleshooting

• UI Won’t Open:  
  • Check plugin is enabled.  
  • Clear browser cookies—test with no plg_system_eprivacy cookie.
• Link Doesn’t Work:  
  • Verify .plg_system_eprivacy_privacy class on menu item (case-sensitive).  
  • Ensure JavaScript isn’t blocked—test in dev tools console.
• Options Missing:  
  • Service integration is hardcoded or requires a companion plugin—check Integration Interface.
• Styling Off:  
  • Confirm Joomla 5’s Bootstrap 5 is loaded—check template settings.  
  • Override with custom CSS if needed.