README

Includes Klaro! consent-manager into TYPO3. Completely file-based configuration for versioning without having to take care of database-entries.

This extension automatically adds a consent-overlay to embedded YouTube- and Vimeo-Videos.

More information on Klaro! can be found here:

• https://klaro.org/docs/getting-started
• https://github.com/klaro-org/klaro-js

UPGRADE v14 - Breaking Changes

• The option etracker.blockScriptBeforeConsent is no longer available. Per default the etracker-scripts are now only loaded when consent is explictly given. However to track users with etrackers cookieless-mode regardless of the given consent just include EXT:klarokratie/Resources/Public/Config/Includes/EtrackerCookieless.js. This compliant with GDPR, see: https://www.etracker.com/en/consent-free-and-legally-compliant/

Installation & Basic Configuration

Simply install the extension.

After installation you can define the path to your Klaro!-configuration in your site configuration (config/sites/<site>/config.yaml). You can also use extension-paths if you use a site-package.

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

Alternatively you can use this older notations (working, but discouraged for the sake of having clear namespaces):

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

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

If you do not define any configuration or custom CSS a default configuration with the default styles is used. However, you can explicitly disable the klaro! Consent Manager by using the following setting:

klarokratie:
    klaro:
        disable: true

or - accordingly the discouraged (!!!) older versions -

klaro:
    disable: true

klaroDisable: true

Modular Configuration using Includes

Starting with the latest version, the Klarokratie extension supports a modular approach to configuration:

• You can define a base configuration file (e.g. KlaroConfigMinimal.js)
• Optionally, you can then provide one or more additional config-files ("includes") that are merged into the base configuration.

This allows you to separate reusable parts and keep your base config clean and minimal.

Example setup:

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 a single combined JavaScript file to reduce HTTP requests. If no includes are defined, only the base config is loaded without merging. This is the default behavior. The extension already comes with several useful includes for common services:

• etracker
• etracker Cookieless & Consent Free (compliant with GDPR, see: https://www.etracker.com/en/consent-free-and-legally-compliant/)
• Meta Pixel / Facebook Pixel
• Google Ads
• Google Analytics
• Google Analytics Cookieless & Consent Free (please be aware that this NOT compliant with GDPR)
• Google Maps
• HCaptcha
• LinkedIn
• Vimeo
• YouTube

These are located in:

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

You can use them directly or copy and customize them in your own site package. Note: if you use includes, the EXT:klarokratie/Resources/Public/Config/KlaroConfigMinimal.js is used instead of EXT:klarokratie/Resources/Public/Config/KlaroConfig.js

You can also override the default translations. You can find an example file here.

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

Just copy it to your site-extension and set your own translations. You can use it like so:

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

Advanced Configuration

Optional: Use Tracking-Code insertion for etracker or Google Analytics

Tracking-code insertion for etracker or Google Analytics is configured via site configuration (config/sites/<site>/config.yaml).

An enabled tracking-code-insertion would either include the current etracker-tracklet or the current Google Analytics tracking code.

Example configuration for etracker:

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

Example configuration for Google Analytics:

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

The following tracking options are available:

etracker

• enable: Enables etracker code insertion.
• secureCode: The secure code of your etracker account.
• blockCookiesOnPageLoad: Enables blocking cookies on page load. This should be active according to GDPR.
• respectDoNotTrack: Respects DoNotTrack in the browser. This should be active according to GDPR.
• doNotUseSessionStorage: Disables Session Storage. Warning: this has a negative impact on page and tracking performance.

Google Analytics

• enable: Enables Google Analytics code insertion.
• useTagManager: Uses Google Tag Manager instead of the Google Analytics tag directly.
• tagId: The tag ID of your Google Analytics or Google Tag Manager account.

There are also Klaro!-configuration-files for etracker and Google Analytics included. These files handle the cookie-opt-in for your tracking according to GDPR. You can use them by setting the desired file in your site configuration:

klarokratie:
    klaro:
        config: EXT:site_default/Resources/Public/Config/KlaroConfigEtracker.js

or

klarokratie:
    klaro:
        config: EXT:site_default/Resources/Public/Config/KlaroConfigGoogleAnalytics.js

If you have a multi-site setup, define different tracking-options in each site's config.yaml.

For backwards compatibility, older site-configuration key names are still supported, but discouraged. Use the klarokratie namespace for new projects:

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

Optional: Categories for etracker (et_areas)

If you use etracker there is a lib-object included which you can use to set hierarchical categories.

IMPORTANT: In order to take effect, you have to use COA-objects in your lib-override-TypoScript!

Below you find a hypothetical example that sets the current domain as first category and as category of the second level the project-name is used that is fetched from the page-properties of the current page via the field "tx_example_project" as reference to table "tx_example_domain_model_project". The example below would result in the following category-value (et_areas) for etracker:

www.mydomain.com/myProjectName

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
                    }
                }
            }
        }
    }
}

Re-Open Modal

If you want to show a menu-item on your website to re-open the modal, this extension adds a field tx_klarokratie_open_modal to the pages-table including the corresponding TCA-configuration for convenient switching using the page properties in the backend. You can use this field to render your menu accordingly and add the required JS to re-open the modal instead of a normal link to the page.

Example:

<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>

Custom CSS

It is possible to include a custom CSS-file for adaption the Klaro! overlay to your needs (see second line above). The CSS partly uses variables which you can override in your custom CSS:

Plain CSS

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: 0px;
    cursor: pointer;
    letter-spacing: 0.01em;
    border: 2px solid #d63f11;
    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 .context-notice .cm-btn.cm-btn-success-var,
body .klaro .cookie-notice .cm-btn.cm-btn-success-var,
body .klaro .cookie-modal .cm-btn.cm-btn-success-var,
body .klaro .cookie-modal .cm-btn.cm-btn-accept,
body .klaro .cookie-modal .cm-btn.cm-btn-decline {
    background-color: #505050;
    border: 2px solid #505050;
}

body .klaro .context-notice .cm-btn.cm-btn-success-var:hover,
body .klaro .cookie-notice .cm-btn.cm-btn-success-var:hover,
body .klaro .cookie-modal .cm-btn.cm-btn-success-var:hover,
body .klaro .cookie-modal .cm-btn.cm-btn-accept:hover,
body .klaro .cookie-modal .cm-btn.cm-btn-decline:hover {
    background-color:#fff;
    color: #505050;
}

body .klaro .context-notice .cm-list-label .slider,
body .klaro .cookie-notice .cm-list-label .slider,
 body .klaro .cookie-modal .cm-list-label .slider {
    background-color: #676767;
}

body .klaro .cookie-modal .cm-caret,
body .klaro .cookie-modal .cm-list-description {
    font-size: 0.8em ;
}

body .klaro .cookie-modal .cm-modal .cm-header,
body .klaro .cookie-modal .cm-list-title {
    font-size: 1.2em;
}

body .klaro .klaro-table + .klaro-table {
    margin-top: 1em
}
body .klaro .klaro-table th{
    padding-right: 1em
}

Example with SASS and Bootstrap

// 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;
    }

    .context-notice .cm-btn.cm-btn-success-var,
    .cookie-notice .cm-btn.cm-btn-success-var,
    .cookie-modal .cm-btn.cm-btn-success-var,
    .cookie-modal .cm-btn.cm-btn-accept,
    .cookie-modal .cm-btn.cm-btn-decline {
        color: $color-white;
        background-color: $color-secondary;

        &:hover {
            background-color: $color-secondary-600;
        }
    }

    .context-notice .cm-list-label .slider,
    .cookie-notice .cm-list-label .slider,
    .cookie-modal .cm-list-label .slider {
        background-color: #676767;
    }

    .cookie-modal .cm-caret,
    .cookie-modal .cm-list-description {
        @include copy-small;
    }

    .cookie-modal .cm-header{
        @include copy;
        .title {
            @include h2;
        }
    }

    .cookie-modal .cm-list-title {
        @include h6;
        margin-bottom: 0
    }

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

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

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

}

Testing

• Single Method

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

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

• Single File

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

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

• All files

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

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

Generate the documentation as HTML

Execute in the extension-root:

docker run --rm --pull always -v "$(pwd)":/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation