Klarokratie

Extension key: klarokratie
Package name: madj2k/t3-klarokratie
Version: main
Language: en
Author: madj2k
License: GPL-2.0-or-later
Rendered: Tue, 30 Jun 2026 07:14:10 +0000

Klarokratie integrates the Klaro! consent manager into TYPO3.

It provides completely file-based configuration, so consent settings can be versioned without managing database entries. The extension can automatically add a consent overlay to embedded YouTube and Vimeo videos.

The extension comes with ready-to-use implemenations for:

etracker
etracker cookieless and consent-free
Meta Pixel / Facebook Pixel
Google Ads
Google Analytics
Google Analytics cookieless (Consent Mode)
Google Maps
HCaptcha
LinkedIn
Vimeo
YouTube

Introduction

What does this extension do?

Klarokratie integrates the Klaro! consent manager into TYPO3.

The extension focuses on file-based configuration. This makes consent-manager settings easy to maintain in version control without having to manage database records.

Klarokratie can automatically add a consent overlay to embedded YouTube and Vimeo videos.

Main features

Integration of the Klaro! consent manager into TYPO3.
File-based configuration for versionable consent settings.
Optional site-specific Klaro! configuration.
Optional custom CSS for adapting the Klaro! overlay.
Modular configuration through include files.
Included configuration snippets for common third-party services.
Optional tracking-code insertion for etracker and Google Analytics.
TYPO3 page-property support for reopening the Klaro! modal.
TypoScript helper for hierarchical etracker categories.

Further information

More information about Klaro! is available at:

Installation

Install the extension

Install the extension in your TYPO3 project.

Composer installation

If your project uses Composer, install the package with:

composer require madj2k/t3-klarokratie

TYPO3 extension installation

After installation, make sure the extension is active in TYPO3.

Basic configuration

Define the path to your Klaro! configuration in the site configuration:

config/sites/<site>/config.yaml

Example:

klarokratie:
    klaro:
        config: EXT:site_default/Resources/Public/Config/KlaroConfig.js
        customCss: EXT:site_default/Resources/Public/Css/Klaro.css

Extension paths can be used when the files are stored in a site package.

Default behavior

If no Klaro! configuration or custom CSS is defined, the default configuration and the default styles are used.

Disable the consent manager

The Klaro! consent manager can be explicitly disabled:

klarokratie:
    klaro:
        disable: true

Older configuration keys

Older configuration keys are still supported, but discouraged. New projects should use the klarokratie namespace.

Older notation:

klaro:
    config: EXT:site_default/Resources/Public/Config/KlaroConfig.js
    customCss: EXT:site_default/Resources/Public/Css/Klaro.css

Alternative older notation:

klaroConfig: EXT:site_default/Resources/Public/Config/KlaroConfig.js
klaroCustomCss: EXT:site_default/Resources/Public/Css/Klaro.css

Older disable notation:

klaro:
    disable: true

klaroDisable: true

Migration

Breaking Changes v14

The option etracker.blockScriptBeforeConsent is no longer available.

By default, etracker scripts are only loaded when consent is explicitly given.

To track users with etracker's cookieless mode regardless of consent, include:

EXT:klarokratie/Resources/Public/Config/Includes/EtrackerCookieless.js

According to etracker, this consent-free mode can be used in a GDPR-compliant way. See:

https://www.etracker.com/en/consent-free-and-legally-compliant/

Configuration

Klarokratie is configured through the TYPO3 site configuration.

config/sites/<site>/config.yaml

Basic Klaro! configuration

Set the JavaScript configuration and optional custom CSS:

klarokratie:
    klaro:
        config: EXT:site_default/Resources/Public/Config/KlaroConfig.js
        customCss: EXT:site_default/Resources/Public/Css/Klaro.css

Configuration options

Name	Type	Default
klarokratie.klaro.config	string	''
klarokratie.klaro.customCss	string	''
klarokratie.klaro.disable	boolean	false
klarokratie.klaro.includes	array	[]

klarokratie.klaro.config

Type: string
Default: ''

Path to the Klaro! JavaScript configuration file.

klarokratie.klaro.customCss

Type: string
Default: ''

Path to a custom CSS file used to style the Klaro! overlay.

klarokratie.klaro.disable

Type: boolean
Default: false

Disables the Klaro! consent manager when set to true.

klarokratie.klaro.includes

Type: array
Default: []

Additional JavaScript configuration files merged into the base configuration.

Default configuration

If no configuration or custom CSS is defined, Klarokratie uses a default configuration with default styles.

Advanced configuration

Klarokratie supports modular configuration through include files.

A base configuration file can be combined with one or more additional configuration files. This keeps reusable service definitions separate from the base configuration.

Example

klarokratie:
  klaro:
    config: EXT:klarokratie/Resources/Public/Config/KlaroConfigMinimal.js
    includes:
      - EXT:klarokratie/Resources/Public/Config/Includes/HCaptcha.js
      - EXT:klarokratie/Resources/Public/Config/Includes/YouTube.js
      - EXT:klarokratie/Resources/Public/Config/Includes/Vimeo.js
      - EXT:klarokratie/Resources/Public/Config/Includes/GoogleAnalytics.js

All configuration scripts are delivered as one combined JavaScript file to reduce HTTP requests.

If no includes are defined, only the base configuration is loaded without merging. This is the default behavior.

Included service configurations

The extension ships with include files for common services:

etracker
etracker cookieless and consent-free
Meta Pixel / Facebook Pixel
Google Ads
Google Analytics
Google Analytics cookieless (Consent Mode)
Google Maps
HCaptcha
LinkedIn
Vimeo
YouTube

Warning

While the cookieless version of etracker can be used in compliance with the GDPR even without explicit consent (see: https://www.etracker.com/en/consent-free-and-legally-compliant/), the use of the cookieless version of Google Analytics (aka Consent Mode) without consent is NOT GDPR-compliant! If you decide to use it anyway, you’ll be operating in a legal gray area, at the very least.

The files are located in:

EXT:klarokratie/Resources/Public/Config/Includes/

They can be used directly or copied and customized in a site package.

Note

If includes are used, EXT:klarokratie/Resources/Public/Config/KlaroConfigMinimal.js is used instead of EXT:klarokratie/Resources/Public/Config/KlaroConfig.js.

Tracking with etracker or Google Analytics

Tracking-code insertion

Klarokratie can optionally insert tracking code for etracker or Google Analytics.

Tracking-code insertion is configured in the site configuration:

config/sites/<site>/config.yaml

When enabled, Klarokratie inserts either the current etracker tracklet or the current Google Analytics tracking code.

Google Analytics

Example configuration:

klarokratie:
    googleAnalytics:
        enable: true
        useTagManager: false
        tagId: G-XXXXXXXXXX

Name	Type	Default
klarokratie.googleAnalytics.enable	boolean	false
klarokratie.googleAnalytics.useTagManager	boolean	false
klarokratie.googleAnalytics.tagId	string	''

klarokratie.googleAnalytics.enable

Type: boolean
Default: false

Enables Google Analytics code insertion.

klarokratie.googleAnalytics.useTagManager

Type: boolean
Default: false

Uses Google Tag Manager instead of the Google Analytics tag directly.

klarokratie.googleAnalytics.tagId

Type: string
Default: ''

The tag ID of the Google Analytics or Google Tag Manager account.

etracker

Example configuration:

klarokratie:
    etracker:
        enable: true
        secureCode: ''
        blockCookiesOnPageLoad: true
        respectDoNotTrack: true
        doNotUseSessionStorage: false

Name	Type	Default
klarokratie.etracker.enable	boolean	false
klarokratie.etracker.secureCode	string	''
klarokratie.etracker.blockCookiesOnPageLoad	boolean	true
klarokratie.etracker.respectDoNotTrack	boolean	true
klarokratie.etracker.doNotUseSessionStorage	boolean	false

klarokratie.etracker.enable

Type: boolean
Default: false

Enables etracker code insertion.

klarokratie.etracker.secureCode

Type: string
Default: ''

The secure code of the etracker account.

klarokratie.etracker.blockCookiesOnPageLoad

Type: boolean
Default: true

Enables blocking cookies on page load. This should be active according to GDPR.

klarokratie.etracker.respectDoNotTrack

Type: boolean
Default: true

Respects the Do Not Track browser setting. This should be active according to GDPR.

klarokratie.etracker.doNotUseSessionStorage

Type: boolean
Default: false

Disables session storage.

Warning

Disabling session storage has a negative impact on page and tracking performance.

etracker categories

Klarokratie includes a TypoScript lib object that can be used to set hierarchical etracker categories through et_areas.

Important

To make the override effective, use COA objects in your lib override TypoScript.

Example result

The following example can create an etracker category value like:

www.mydomain.com/myProjectName

TypoScript example

lib {
    txKlarokratie {
        etracker {

            domain = COA
            domain {
                10 = TEXT
                10.data = getIndpEnv:HTTP_HOST
            }

            categoryLevel1 = COA
            categoryLevel1 {
                30 = RECORDS
                30 {
                    source.data = levelfield: -1 , tx_example_project, slide
                    tables = tx_example_domain_model_project
                    conf.tx_example_domain_model_project = TEXT
                    conf.tx_example_domain_model_project {
                        field = name
                        override.field = short_name
                    }

                    // Default value if empty
                    stdWrap.ifEmpty.cObject = COA
                    stdWrap.ifEmpty.cObject {
                        10 = TEXT
                        10.value = Default
                    }
                }
            }
        }
    }
}

Klaro! presets for tracking

The extension includes Klaro! configuration files for etracker and Google Analytics. These files handle cookie opt-in for tracking.

etracker preset:

klarokratie:
    klaro:
        config: EXT:klarokratie/Resources/Public/Config/KlaroConfigMinimal.js
        includes:
          - EXT:klarokratie/Resources/Public/Config/Includes/Etracker.js

Google Analytics preset:

klarokratie:
    klaro:
        config: EXT:klarokratie/Resources/Public/Config/KlaroConfigMinimal.js
        includes:
          - EXT:klarokratie/Resources/Public/Config/Includes/GoogleAnalytics.js

Translation

Default translations can be overridden with an override file.

Example files are located in:

EXT:klarokratie/Resources/Public/Config/Overrides/

Copy the override file to your site package and add it as an include:

klarokratie:
  klaro:
    config: EXT:klarokratie/Resources/Public/Config/KlaroConfigMinimal.js
    includes:
      - EXT:site_default/Resources/Public/Config/Overrides/Translations.js

Custom CSS

A custom CSS file can be included to adapt the Klaro! overlay.

Add the CSS file in the site configuration:

klarokratie:
    klaro:
        customCss: EXT:site_default/Resources/Public/Css/Klaro.css

Plain CSS example

body .klaro {
    --green1: #d63f11;
    --green2: #d63f11;
    --green3: #d63f11;
    --font-family: Helvetica, Arial, sans-serif;
}

body .klaro .context-notice {
    background-color: #f2f2f2;
    font-size: 1.2em;
}

body .klaro label {
    margin: 0;
}

body .klaro .purposes {
    display: none;
}

body .klaro .cookie-modal .cm-btn,
body .klaro .context-notice .cm-btn,
body .klaro .cookie-notice .cm-btn {
    text-transform: uppercase;
    font-size: 14px;
    font-weight: 600;
    border-radius: 8px;
    display: inline-block;
    border: 2px solid #d63f11;
    cursor: pointer;
    letter-spacing: 0.01em;
    transition: all 0.2s ease-out;
    line-height: 1.2;
    text-align: center;
    padding: 12px;
}

body .klaro .cookie-modal .cm-btn:hover,
body .klaro .context-notice .cm-btn:hover,
body .klaro .cookie-notice .cm-btn:hover {
    background-color: #fff;
    color: #d63f11;
}

body .klaro .klaro-table + .klaro-table {
    margin-top: 1em;
}

body .klaro .klaro-table th {
    padding-right: 1em;
}

Sass and Bootstrap example

// We need at least the mixins
@import "../../node_modules/bootstrap/scss/mixins";

@import "default/00_mixins/_import";
@import "default/10_config/_variables";
@import "default/10_config/_maps";
@import "default/20_basics/_cta";

body .klaro {
    --green1: #{$color-primary};
    --green2: #{$color-primary};
    --green3: #{$color-primary};
    --font-family: #{$font-family-sans-serif};

    &.cm-as-context-notice {
        padding: 0;
    }

    .context-notice {
        @include copy;
        background-color: $color-secondary-200;
        border-color: $color-secondary;
        border-radius: 0;
    }

    label {
        margin: 0;
    }

    .purposes {
        display: none;
    }

    .cookie-modal .cm-btn,
    .context-notice .cm-btn,
    .cookie-notice .cm-btn {
        border-radius: 0;
        @extend .cta;
        @extend .cta-small;
    }

    .cookie-modal .cm-footer-buttons {
        margin-top: 1rem;
    }

    .klaro-table + .klaro-table {
        margin-top: 1em;
    }

    .klaro-table th {
        padding-right: 1em;
    }
}

Modal

Reopen the Klaro! modal

Klarokratie adds the field tx_klarokratie_open_modal to the TYPO3 pages table and provides the corresponding TCA configuration.

This field can be enabled in the page properties and used to render a menu item that reopens the Klaro! modal instead of linking to a normal page.

Example Fluid markup:

<a class="nav-link {f:if(condition:'{menuItem.active}', then:'active')}"
   href="{f:if(condition:'{menuItem.data.tx_klarokratie_open_modal}', then:'#', else:'{menuItem.link}')}"
   {f:if(condition:'{menuItem.data.tx_klarokratie_open_modal}', then:'onclick="javascript:klaro.show(undefined, true);return false;"')}
   target="{menuItem.target}"
   title="{menuItem.title}"
   role="menuitem">
    <span>{title}</span>
</a>

Developer

Testing

The extension contains unit and functional tests.

Run a single unit-test method

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-klarokratie/phpunit.xml \
    vendor/madj2k/t3-klarokratie/Tests/Unit/Whatever/Whatever.php \
    --filter MethodName

Run a single functional-test method

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-klarokratie/phpunit.functional.xml \
    vendor/madj2k/t3-klarokratie/Tests/Functional/Whatever/Whatever.php \
    --filter MethodName

Run a single unit-test file

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-klarokratie/phpunit.xml \
    vendor/madj2k/t3-klarokratie/Tests/Unit/Whatever/Whatever.php

Run a single functional-test file

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-klarokratie/phpunit.functional.xml \
    vendor/madj2k/t3-klarokratie/Tests/Functional/Whatever/Whatever.php

Run all unit tests

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-klarokratie/phpunit.xml

Run all functional tests

ddev exec vendor/bin/phpunit -c vendor/madj2k/t3-klarokratie/phpunit.functional.xml