@netgen/javascript-cookie-control

Javascript cookie control

Javascript module for controling cookie consent on your website.

Install

Install the Node dependency:

yarn add @netgen/javascript-cookie-control

or

npm install --save @netgen/javascript-cookie-control

Load

To load the required ES2015 module:

import CookieControl from '@netgen/javascript-cookie-control';

Usage

HTML

HTML markup for cookie control window shoud be:

<div id="ng-cc">

    <!-- if you don't want to use the overlay, remove next div from the markup -->
    <div class="ng-cc-overlay"></div>

    <!-- button for opening the window. Leave out if you don't need it -->
    <a href="#" class="js-open-ng-cc">Cookie settings</a>

    <div class="ng-cc-modal">

        <!-- button for closing the window. Leave out if you don't need it -->
        <a href="#" class="ng-cc-close ng-cc-close-btn">close</a>

        <div class="ng-cc-content">
            <div class="wrapper">
                <h3>This site uses cookies.</h3>
                <p>Some text describing your cookie usage...</p>

                <div class="ng-cc-actions">
                    <a href="#" class="optional-list-toggle">
                        <span>Customize settings!</span>
                        <span class="cookie-angle-up"></span>
                    </a>

                    <!-- button for accepting selected cookies and closing the window -->
                    <button id="ng-cc-accept" class="btn btn-primary">I'm ok with this</button>
                </div>
            </div>
            <div class="ng-cc-optional-list">
                <ul>
                    <!-- markup for the single cookie group (should be the same as the ones generated with js) -->
                    <li>
                        <input type="checkbox" class="ng-cc-optional-checkbox" id="ng-cc-necessary" data-name="necessary" checked disabled />
                        <label for="ng-cc-necessary">
                            <i class="ng-cc-checkbox-icon">
                              <span class="on ng-cc-on">Accepted</span>
                              <span class="off ng-cc-off">Not accepted</span>
                            </i>
                            Necessary Cookies
                        </label>
                        <p>This website cannot function properly without these cookies.</p>
                    </li>

                    <!-- this is where optional cookie groups are rendered -->
                </ul>
                <div class="ng-cc-optional-actions clearfix">
                  <button id="ng-cc-optional-save" class="btn btn-outline-primary">
                    Save settings
                  </button>
                </div>
            </div>
        </div>
    </div>
</div>

JS

Create config object for cookie control plugin and initialize it:

const ccConfig = {
  options: {
    lifetime: 30,
  },
  optionalCookies: [
    {
      name: 'analytics',
      label: 'Analytical Cookies',
      description: 'Analytical cookies help us to improve our website by collecting and reporting information on its usage.',
      accepted: true,
      onRevoke() {
        window['ga-disable-XX-XXXXX-X'] = true;
      },
    },
    {
      name: 'marketing',
      label: 'Marketing Cookies',
      description: 'We use marketing cookies to help us improve the relevancy of advertising campaigns you receive.',
    },
    {
      name: 'socialsharing',
      label: 'Social Sharing Cookies',
      description: 'We use some social sharing plugins, to allow you to share certain pages of our website on social media',
      onAccept: () => {
        (function(d, s, id) {
          var js, fjs = d.getElementsByTagName(s)[0];
          if (d.getElementById(id)) return;
          js = d.createElement(s); js.id = id;
          js.src = 'https://connect.facebook.net/en_GB/sdk.js#xfbml=1&version=v3.0';
          fjs.parentNode.insertBefore(js, fjs);
        }(document, 'script', 'facebook-jssdk'));
      },
    },
  ],
};

// create new cookie control instance
const cookieControl = new CookieControl(ccConfig);
// initialize the plugin
cookieControl.init();

Second parameter for initializing new instance is optional string with the id of the plugin div. Default value is ng-cc. So if you need to change it, use it like this:

const cookieControl = new CookieControl(ccConfig, 'new-id');

Parameters for cookie control config:

Config object has two parameters.

Parameter	Type	Default value	Description
options	Object		General options for the plugin
optionalCookies	Array		Array of objects for optional cookie groups

Parameters for the options object (all are optional):

Parameter	Type	Default value	Description
open	boolean	true	Open the window on page load (doesn't open once the user accepts the cookies)
lifetime	number	365	Lifetime of the saved cookie settings (in days)
domain	string		Domain for the saved cookie (e.g., 'example.com' or 'subdomain.example.com'). If not specified, this defaults to the host portion of the current document location.
acceptValue	string	'1'	Value saved for the accepted cookie group
revokeValue	string	'0'	Value saved for the revoked cookie group
timeout	number	200	Timeout for auto open on page load (in milliseconds)
optionCookieHtml(cookie)	function		Function returning template for single optional cookie group. Function takes one object as parameter which has values for name (string), label (string), description (string) and accepted (boolean) and should return string with html
onChange(event, instance)	function		Function that gets executed on cookie group checkbox change. Function has two arguments. First one is checkbox change event from which you can get cookie group name (e.target.dataset.name) and if it's accepted or not (e.target.checked), and the other is instance of the plugin
onAccept(instance)	function		Function that gets executed on cookie accept button. Function has one argument, instance of the plugin

Parameters for each optionalCookies object:

Parameter	Type	Default value	Description
name	string		Name of the cookie group (used for storing the value)
label	string		Label for cookie group which is rendered in window next to the checkbox
description	string		Description for the cookie group rendered below checkbox and label
cookieName (optional)	string	ng-cc- + name	Name for storing cookie group consent
accepted (optional)	boolean	false	Set to true if you want that cookie group to be enabled by default
onAccept (optional)	function		Function that gets executed on plugin init if the cookie group is enabled
onRevoke (optional)	function		Function that gets executed on plugin init if the cookie group is disabled

You can modify options of the plugin after creating the instance with set('option', new_value) function. e.g.:

cookieControl.set('onChange', (e, instance) => {
  console.log(e, instance);
});

Behaviour

There is an event listener for the click on html elements containing css class js-open-ng-cc which opens the window. You can put it anywhere on your site if you need to.

On every cookie group checkbox change, plugin saves the cookie with that cookie name and accept or revoke value.

Window opens on every page load until user clicks the #ng-cc-accept button (if the open parameter isn't set to false). After that, the window doesn't open automatically for the duration of the cookie lifetime.

SCSS

Import styles to scss file:

@import "@netgen/javascript-cookie-control/scss/style";

You also need to configure sass-loader to understand imports from node_modules. Update your sass-loader config by changing { loader: 'sass-loader' } to:

{
  loader: 'sass-loader',
  options: {
    includePaths: ['node_modules']
  }
}

You can override scss variables for main div id, plugin window width and background:

$ngCcId: 'ng-cc';
$ngCcWidth: 28em;
$ngCcBg: hsl(0, 0, 15);