npm package: @nationalarchives/frontend-cookie-banner
Description: The National Archives frontend cookie banner
Author: Andrew Hosgood
Latest version: 0.6.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

<img src="../../assets/images/tna-square-logo.svg" alt="The National Archives logo" title="The National Archives" width="100" />

# TNA Frontend Cookie Banner

[![Latest release](https://img.shields.io/github/v/release/nationalarchives/tna-frontend?style=flat-square&logo=github&logoColor=white&sort=semver)](https://github.com/nationalarchives/tna-frontend/releases)
[![NPM version](https://img.shields.io/npm/v/@nationalarchives/frontend-cookie-banner?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@nationalarchives/frontend-cookie-banner)
[![Licence](https://img.shields.io/github/license/nationalarchives/tna-frontend?style=flat-square)](https://github.com/nationalarchives/tna-frontend/blob/main/LICENCE)

Use the cookie banner from TNA Frontend in your service.

## HTML

```html
<section class="tna-cookie-banner" data-module="tna-cookie-banner" data-policies="" data-preferences-key="" data-policies-key="" data-domain="myservice.nationalarchives.gov.uk" data-path="/" data-insecure="false" aria-label="Cookies on my service" hidden>
  <div class="tna-container">
    <div class="tna-column tna-column--full tna-cookie-banner__message tna-cookie-banner__message--prompt">
      <h2 class="tna-heading-m">This website uses cookies</h2>
      
      <p>We use some essential cookies to make this service work.</p>
      <p>We'd also like to use analytics cookies so we can understand how you use the service and make improvements.</p>
      
      <div class="tna-button-group">
        <button class="tna-button" type="button" value="accept">
          Accept cookies
          </button>
        
        <button class="tna-button" type="button" value="reject">
          Reject cookies
          </button>
        
        <a href="/cookies" class="tna-button tna-button--plain">
          Set cookie preferences
          </a>
        
      </div>
    </div>
    <div class="tna-column tna-column--full tna-cookie-banner__message tna-cookie-banner__message--accepted" tabindex="0" hidden>
      
      <p>You have accepted optional cookies. You can change your cookie settings on the <a href="/cookies">cookies page</a>.</p>
      
      <div class="tna-button-group">
        <button class="tna-button" type="button" value="close">
          Hide cookies message
          </button>
        
      </div>
    </div>
    <div class="tna-column tna-column--full tna-cookie-banner__message tna-cookie-banner__message--rejected" tabindex="0" hidden>
      
      <p>You have rejected optional cookies. You can change your cookie settings on the <a href="/cookies">cookies page</a>.</p>
      
      <div class="tna-button-group">
        <button class="tna-button" type="button" value="close">
          Hide cookies message
          </button>
        
      </div>
    </div>
  </div>
</section>
```

### Attributes

| Attribute             | Purpose                                                                   | Default                  |
| --------------------- | ------------------------------------------------------------------------- | ------------------------ |
| `data-policies`       | Extra cookie policies in addition to "essential", "settings" and "usage"  | [none]                   |
| `data-preferenceskey` | The cookie name to state that the user preferences have already been set  | `cookie_preferences_set` |
| `data-policieskey`    | The cookie name for the policy preferences                                | `cookies_policy`         |
| `data-domain`         | The domain to save cookies for                                            | [The current domain]     |
| `data-path`           | The path that cookies are available within                                | `/`                      |
| `data-insecure`       | Allow cookies to be sent in HTTP environments (designed for testing only) | `false`                  |

## JavaScript

### Initialise the component

Include the JavaScript in your service. This should add a `TNAFrontend` object to your `window`. You can then initialise the component:

```js
const $cookieBanner = document.querySelector(
  '[data-module="tna-cookie-banner"]',
);

if ($cookieBanner) {
  new TNAFrontend.CookieBanner($cookieBanner);
}
```

### Work with cookies using the `Cookies` class

```js
import Cookies from "@nationalarchives/frontend/nationalarchives/lib/cookies.mjs";

const cookies = new Cookies();

if (cookies.isPolicyAccepted("usage")) {
  // Add tracking code
}
```

#### Use cookie events

```js
import Cookies from "@nationalarchives/frontend/nationalarchives/lib/cookies.mjs";

const cookies = new Cookies();

cookies.on("acceptPolicy", function(policy) {
  if (policy === "usage") {
    console.log("Usage cookies are permitted");
    // Add tracking code
  }
});

cookies.on("rejectPolicy", function(policy) {
  if (policy === "usage") {
    console.log("Usage cookies have been rejected");
    // Remove tracking code
  }
});
```

| Event               | Trigger                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------- |
| `setCookie`         | Any time a cookie is changed in the browser using the `Cookie` class                        |
| `deleteCookie`      | When any cookie is deleted using `delete()`                                                 |
| `deleteAllCookies`  | When all cookies are deleted using `deleteAll()`                                            |
| `acceptPolicy`      | When any policy is accepted using `acceptPolicy()`                                          |
| `acceptAllPolicies` | When all policies are accepted using `acceptAllPolicies()`                                  |
| `rejectPolicy`      | When any policy is rejected using `rejectPolicy()`                                          |
| `rejectAllPolicies` | When all policies are rejected using `rejectAllPolicies()`                                  |
| `changePolicy`      | When any policy is changed using either `acceptPolicy()`, `rejectPolicy()` or `setPolicy()` |