dutchheight / craft-cookie-boss

Allow your visitors to set their cookie preference.
Other
3 stars 1 forks source link

Screenshot

Craft Cookie boss plugin for Craft CMS 3.x

Allow your visitors to set their cookie preference which you can use to enable features in your site. Create your own cookie groups, make them required and/or set their default state. These cookie groups can contain cookies with information which you can display to describe the purpose of each cookie.

Create own cookie groups Add cookies to cookie groups

The default modal contains the following features:

Modal with settings:

Modal with settings

Modal settings:

Modal without settings

Modal without settings:

Modal without settings

Requirements

This plugin requires Craft CMS 3.0.0 or later.

Installation

To install the plugin, follow these instructions.

  1. Open your terminal and go to your Craft project:

    cd /path/to/project
  2. Then tell Composer to load the plugin:

    composer require dutchheight/craft-cookie-boss
  3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Craft Cookie boss.

  4. Add {{ craft.cookieBoss.askConsent() }} on the page(s) which should display the modal.

Using Craft Cookie boss

Display the consent modal

craft.cookieBoss.askConsent(options, force) is used to display the default consent modal.

Attribute Type Required Description
options object false Accepts position ('top or bottom-left or right')
force boolean false Force the modal

Examples

Display the modal craft.cookieBoss.getConsents()

Display the modal in the top right corner craft.cookieBoss.getConsents({'position': 'top-right'})

Display the modal always:

{{ craft.cookieBoss.getConsents({}, true) }}

Display cookie descriptions

Display a table with all enabled cookies. The table has #cookie-descriptions as id. Each cookie is provided with the class .consent-true or .consent-false depending on the consentgroup's consent. All cookies are grouped by their group which has the class .cookie-descriptions-group-title. If you like more control you can use craft.cookieBoss.getCookiesRaw().

Examples

Display a table with all enabled cookies

{{ craft.cookieBoss.getCookies() }}

Display cookie group toggle checkbox

Displays a checkbox which toggles the specified consent group. For more control see 'Toggle consent group with a form'

Attribute Type Required Description
handle string true Use a handle from the settings

Examples

Display a checkbox which can be used to toggle a consent group

{{ craft.cookieBoss.toggleConsentGroupForm('marketing') }}

Get all visitor consents

craft.cookieBoss.getConsents(defaultConcentIfNotSet) is used to get an array with the visitor's consents.

Attribute Type Required Description
defaultConcentIfNotSet boolean false return the default consents if the visitor doens't have any consents

Examples

Get all consents of the current visitor craft.cookieBoss.getConsents()

Get all consents of the current visitor. Get default values if noting found. craft.cookieBoss.getConsents(true)


Get visitor consent date

craft.cookieBoss.getConsentGiveAt(format) is used to get the unix time or formated date of the visitor's consents.

Attribute Type Required Description
format string false Format the timestamp

Examples

Get the current visitor time of consent. craft.cookieBoss.getConsentGiveAt()

Get the current visitor time of consent in given format. craft.cookieBoss.getConsentGiveAt("d-m-Y")


Get if visitor gave consent for cookie group

craft.cookieBoss.isConsentWith(handle) is used to get the consent of the current visitor by handle.

Attribute Type Required Description
handle string true Use a handle from the settings

Examples

Get consents of the current visitor

{% if craft.cookieBoss.isConsentWith('marketing') %}
    We have permission to do marketing stuff
{% endif %}

Get all consent groups

craft.cookieBoss.getConsentsGroupsRaw(false) is used to get all consent groups.

Attribute Type Required Description
onlyEnabled boolean false Only return enabled consent groups

Examples

Get all consent groups.

craft.cookieBoss.getConsentsGroupsRaw()

Get all consent groups by handle

craft.cookieBoss.getConsentsGroupRawByHandle(consentGroupHandle) is used to get all cookie groups by handle.

Attribute Type Required Description
consentGroupHandle string true Use a handle from the settings

Examples

Get all cookie groups by handle.

craft.cookieBoss.getConsentsGroupRawByHandle()

Get all cookie descriptions

craft.cookieBoss.getCookiesRaw() is used to get all cookie descriptions. craft.cookieBoss.getCookiesRaw(consentGroupHandle) is used to get all cookie descriptions for a consent group.

Attribute Type Required Description
consentGroupHandle string true Use a handle from the settings

Examples

Get all cookie descriptions

craft.cookieBoss.getCookiesRaw()

Custom modal

craft.cookieBoss.getConsentsGroupsRaw() will return all raw data which you can use to create a custom modal.

Save the settings

/craft-cookie-boss/save-consent-settings accepts POST requests with new consent settings. Usage of the Craft csrf token is required. Use craft.app.request.csrfParam to get the key and craft.app.request.csrfToken to get the actual token.

Attribute Type Required Description
toggled object true Use a handle from the settings
csrfParam string true Craft csrf token. Use the csrfParam as key

Example request data

    "groups": {
        "technical": true,
        "marketing": false
    },
    "CRAFT_CSRF_TOKEN": "ABC...XYZ"

Toggle a consent group with a custom form

Do a POST request to /cookie-boss/toggle-consent-group. For each group you wish to toggle you need to pass a boolean represented by the handle name.

Example form

{% set handle = 'marketing %}
{% set consentGroup = craft.cookieBoss.getConsentsGroupRawByHandle(handle) %}
<form id="toggle-{{ handle }}-form" action="/cookie-boss/toggle-consent-group" method="POST">
    {{ csrfInput() }}
    {{ redirectInput(craft.app.request.pathInfo) }}
    <input type="hidden" name="groups[marketing]" value="" />
    <input type="checkbox" class="inline js-toggle-consentGroup ml-2" value="true"
        name="groups[{{ handle }}]"
        onchange="document.getElementById('toggle-{{ handle }}-form').submit();"
        id="toggle-{{ handle }}-checkbox"
        {% if consentGroup.required %} disabled {% endif %}
        {% if consentGroup.hasConsent() or consentGroup.required %}checked {% endif %}>
</form>

Craft Cookie Boss Roadmap

Some things to do, and ideas for potential features:

Brought to you by Dutch Height