Cookieman
=========

|Crowdin|

! Warnings !
------------

Expect some days until this is fixed:

This documentation is still v1 and not proper for the current v2.

Currently only the example theme ``bootstrap4-modal`` is v2-ready.

Choose your branch: 8lts (TYPO3 8.7), 9lts (TYPO3 9.5), master (TYPO3
10.x).

To try it: just run ``ddev start`` which will install a TYPO3 with
example content and ``cookieman``.

How it works
------------

It includes the HTML for a cookie confirmation modal on every page.

It shows the modal when the cookie *CookieConsent* is not set yet. In
the example templates it is not shown on the configured imprintPid and
dataProtectionDeclarationPid (see TypoScript constants) - this is to
follow the GDPR’s expectation that those pages shall be easily and
directly accessible and should not interfere with a cookie consent
banner.

It is recommended to include a snippet like that on your data protection
page to allow your users to adjust their cookie preferences:

.. raw:: html

   <pre>
   &lt;a href="" onclick="cookieman.show(); return false"&gt;
     Adjust your cookie preferences
   &lt;/a&gt;
   </pre>

It saves the user’s choices as a comma-separated list of groups in the
HTML cookie *CookieConsent*, e.g. “marketing,preferences”.

Your tracking solutions shall then adhere to this setting by checking if
their repective string (e.g. “marketing”) is contained in the cookie
*CookieConsent*. You should also pay respect to the “Do-not-track”
setting of your users which is sent as HTTP-Header ``DNT: 1`` and
accessible in JavaScript via ``navigator.doNotTrack``. The example
templates include a dynamic text block that show this browser setting.

This can be done in Google Tagmanager or by dynamically including
<script>s with JavaScript.

.. raw:: html

   <pre>
   (function() {
       if (
         !(navigator.doNotTrack && navigator.doNotTrack === '1') 
         && cookieman.hasConsented('marketing')
       ) {
           // if you need a &lt;script src=""&gt; tag
           var _tagSrc = document.createElement('script')
           _tagSrc.src = 'https://mytrackingthingie.com/anal.js'
           document.head.appendChild(_tagSrc)

           // if you need &lt;script&gt; tag content
           var _tagContent = document.createElement('script')
           _tagContent.textContent = 'alert("some content")'
           document.head.appendChild(_tagContent)
       }
   })()
   </pre>

You could of course let your server handle that, too (in PHP,
TypoScript, e.g.) but this is IMHO overkill and should only be necessary
for edge cases.

Requirements
------------

-  If you reimplement your own theme, it has no requirements at all
-  for the example HTML templates

   -  Bootstrap 3 CSS
   -  Bootstrap 3 JavaScript for *collapse*\ s and *modal*\ s
   -  jQuery

Installation
------------

composer
~~~~~~~~

Get it from packagist https://packagist.org/packages/dmind/cookieman

Run composer req dmind/cookieman

Integration
-----------

Include the TypoScript and adjust the constants.

It should get loaded automatically on every (except imprint and data
protection declaration) page. If it does not, check for errors in a
JavaScript console when calling ``cookieman.show()`` manually.

Create a new theme
~~~~~~~~~~~~~~~~~~

Copy the EXT:cookieman/Resources/ folder to your site package extension
and set the ``plugin.tx_cookieman.settings.resourcesBasePath``
TypoScript constant. Choose a theme name, set it in the constant
``plugin.tx_cookieman.settings.theme`` and rename the example folders
(e.g. bootstrap3-banner) to your name.

Adapt the HTML/CSS/JS as needed. These elements control the
functionality: \* <\* data-cookieman-save> - save and close \* <\*
data-cookieman-accept-all> - accept all \* <form data-cookieman-form> -
the form that contains all checkboxes \* change the checkboxes’ name=“…”
to a value that you expect to find in the CookieConsent when the user
consented (in the examples only one group called “marketing” is
included)

If you are working a non-Bootstrap environment, you will have to
reimplement the methods cookieman.show() and cookieman.hide() (see the
example code in ``JavaScript/cookieman-theme.js``).

API
---

JavaScript
~~~~~~~~~~

cookieman.js exposes these methods:

*cookieman.showOnce()*: void
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   Shows the confirmation modal only when the user preferences in the
   cookie *CookieConsent* are not yet present.

*cookieman.show()*: void
^^^^^^^^^^^^^^^^^^^^^^^^

   Shows the confirmation modal. You can call that from anywhere you
   need it (e.g. with a link from your data protection declaration
   page).

   .. raw:: html

      <pre>
      &lt;a href="" onclick="cookieman.show(); return false"&gt;
        Cookie settings
      &lt;/a&gt;
      </pre>

*cookieman.hide()*: void
^^^^^^^^^^^^^^^^^^^^^^^^

   Hides the confirmation modal.

*cookieman.hasConsented(selection)*: Boolean
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   Returns true if the user has consented to the given selection, else
   false. A selection is any name of a checkbox in the popup,
   e.g. ‘marketing’

Cookieman also includes the (1kB) cookie library `JavaScript
Cookie <https://github.com/js-cookie/js-cookie>`__ that also exposes its
API and makes it easier to work with cookies.

TODO
====

Translations
------------

Document
--------

Mention https://www.cookieserve.com/
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Browser support
~~~~~~~~~~~~~~~

ddev install-git-hooks
~~~~~~~~~~~~~~~~~~~~~~

Branches, Releases
------------------

git clean when changing branches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

testing extension for Bootstrap 3
---------------------------------

Access crowdin from ddev Development:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

DNT per group respected
~~~~~~~~~~~~~~~~~~~~~~~

Not shown on Imprint and Data Declaration Page

ddev TYPO3 backend admin: admin / adminadmin

Browser compat: IE11, Firefox, Chrome, Safari

supports: <script> / img / any HTML

add hooks

Example
-------

temp.tx_cookieman.settings.groups.mandatory <
plugin.tx_cookieman.settings.groups.mandatory

plugin.tx_cookieman.settings { trackingObjects { # extend the existing
configuration for ‘Matomo’ Matomo { inject (

.. raw:: html

   <script type="text/javascript">
     var _paq = window._paq || [];
     _paq.push(['trackPageView']);
     _paq.push(['enableLinkTracking']);
     (function() {
       var u="//my-piwik-server.my-domain.com/";
       _paq.push(['setTrackerUrl', u+'matomo.php']);
       _paq.push(['setSiteId', 'my site ID']);
       var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
       g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
     })();
   </script>

::

       )
   }

   # add my own custom tracking solution
   MyOwnTrackingPixel {
     inject (

.. container::

   Here be dragons 

::

     )
     show {
       # each element here represents one line of information in the consent popup
       pixelphp {
         duration = 1
         durationUnit = months
         type = pixel
         provider = My Website Inc.
       }
     }
   }

}

# reset existing groups groups > groups { # copy of default group
‘mandatory’ mandatory < temp.tx_cookieman.settings.groups.mandatory

::

   # my new group
   mygroup {
     trackingObjects {
        0 = Matomo
        1 = MyOwnTrackingPixel
     }
   }

} }

plugin.tx_cookieman._LOCAL_LANG { en { trackingobject.pixelphp = You can
translate the name, but you do not have to. trackingobject.pixelphp.desc
= My own tracking pixel does not really track you. It’s just here to
cheer you up. group.mygroup = My group is my castle. } default < .en }

.. |Crowdin| image:: https://badges.crowdin.net/typo3-extension-cookieman/localized.svg
   :target: https://crowdin.com/project/typo3-extension-cookieman