zephir / kirby-cookieconsent
Kirby cookieconsent plugin
Installs: 1 164
Dependents: 0
Suggesters: 0
Security: 0
Stars: 47
Watchers: 4
Forks: 2
Open Issues: 1
Type:kirby-plugin
Requires
README
A plugin to implement cookieconsent in Kirby.
- Uses the open source cookieconsent library
- Provides default translations for 5 cookie categories
- Multilingual support (EN/DE/FR)
- Customizable
Table of Contents
1. Installation
The recommended way of installing is by using Composer.
1.1 Composer
composer require zephir/kirby-cookieconsent
1.2 Download
Download and copy this repository to /site/plugins/kirby-cookieconsent
.
1.3 Git submodule
git submodule add https://github.com/zephir/kirby-cookieconsent.git site/plugins/kirby-cookieconsent
2. Setup
Add snippet('cookieconsentCss')
to your header and snippet('cookieconsentJs')
to your footer.
3. Options
3.1 Available options
3.2 Defaults
'zephir.cookieconsent' => [ 'cdn' => false, 'revision' => 1, 'root' => 'document.body', 'autoClearCookies' => true, // Only works when the categories have an autoClear array 'autoShow' => true, 'hideFromBots' => true, 'disablePageInteraction' => false, 'lazyHtmlGeneration' => true, 'guiOptions' => [ 'consentModal' => [ 'layout' => 'box', 'position' => 'bottom right', 'flipButtons' => false, 'equalWeightButtons' => true ], 'preferencesModal' => [ 'layout' => 'box', // 'position' => 'left', // only relevant with the "bar" layout 'flipButtons' => false, 'equalWeightButtons' => true ] ], 'categories' => [ 'necessary' => [ 'enabled' => true, 'readOnly' => true ], 'measurement' => [], 'functionality' => [], 'experience' => [], 'marketing' => [] ], 'translations' => [ 'de' => require_once(__DIR__ . '/translations/de.php'), 'en' => require_once(__DIR__ . '/translations/en.php'), 'fr' => require_once(__DIR__ . '/translations/fr.php') ], 'language' => [ 'locale' => 'en', 'direction' => 'ltr' ] ]
3.3 Predefined cookie categories
Each cookie category can be used to control certain scripts. To learn how to manage scripts, head over to the CookieConsent documentation.
Categories that are predefined by this plugin:
Predefined means that there are translations in all languages for each category.
To enable/disable categories you can use the categories
option of the plugin.
'zephir.cookieconsent' => [ 'categories' => [ 'necessary' => [ 'enabled' => true, // marks the category as enabled by default 'readOnly' => true ], 'measurement' => [], 'functionality' => [], 'experience' => [], 'marketing' => [] ], ]
An empty array defines the category with the default options. You can pass additional options like
enabled
orreadOnly
in the array. Learn more about those options in the CookieConsent Documentation.
3.4 Removing a category
To remove a category you have to set its value to false
.
'zephir.cookieconsent' => [ 'categories' => [ 'necessary' => [ 'enabled' => true, 'readOnly' => true ], 'measurement' => [], 'functionality' => false, // will not be shown 'experience' => false, // will not be shown 'marketing' => [] ], ]
4. Language
If you have a single language setup (kirby option languages
not set to true
), you will have to define the language
option of the plugin.
For multi-language setups you don't have to do anything, the plugin automatically uses the kirby language or falls back to the first translation in the translations array.
'zephir.cookieconsent' => [ 'language' => [ 'locale' => 'de', // The translation to use, default is en 'direction' => 'ltr' // Either ltr or rtl, default is ltr ] ]
5. Translations
The translations are a central part of the plugin. By default, we provide translations for EN, DE, FR and the categories mentioned in 3.3 Predefined cookie categories.
To customise or override the default translations, you will need to use the translations
option.
5.1 Overriding specific translations
For this example we are overriding one string and adding a new category in the sections part of the EN translation.
- Create a new folder in your project. For this example we call it
cc-translations
. - In that folder, create a new file
en.php
.
<?php // site/cc-translations/en.php return array_replace_recursive( // We assume the plugin was installed as suggested in the installation section of the readme. require_once(__DIR__ . '/../plugins/kirby-cookieconsent/translations/en.php'), [ 'consentModal' => [ 'title' => 'Lorem ipsum dolor!', // Override consentModal title ], "preferencesModal" => [ "sections" => [ [ // Add a new category in sections "title" => "Custom scripts", "description" => "Diese Cookies helfen uns, Ihnen personalisierte Werbung oder Marketinginhalte bereitzustellen und deren Leistung zu messen.", "linkedCategory" => "custom-scripts", ], ] ] ] );
- Now you need to require (or include) this file in
config.php
. Because we want to see the new categorycustom-scripts
we also need to update thecategories
option.
'zephir.cookieconsent' => [ 'categories' => [ 'custom-scripts' => [] ], 'translations' => [ 'en' => require_once(__DIR__ . '/../cc-translations/en.php') ] ]
You can override the whole translation file by copying the default file and adjusting the values. You can also require the default translation and manually alter the array by modifying, adding or deleting entries.
6. Events
You can find all available events in the CookieConsent Documentation.
The CookieConsent object is available through the window object (
window.CookieConsent
).
License
MIT