npm package: @perplex-digital/athlon-cookie-bar
Description: ## Installation
Latest version: 2.2.0

# athlon-cookie-bar

## Installation

### ES imports

```zsh
npm i @perplex-digital/athlon-cookie-bar
```

Import the registration of `<athlon-cookie-bar>` via:

```javascript
import '@perplex-digital/athlon-cookie-bar';
```

## Usage

### Arguments

The component takes two arguments: umbraconodeid and culture
Option | Type | Default | Description
------ | ---- | ------- | ----
umbraconodeid | string | null | Umbraco node id (GUID)
culture | string | null | Umbraco culture

```html
<athlon-cookie-bar umbraconodeid="xxxxxxxxxx" culture="en"></athlon-cookie-bar>
```

## Interaction with cookies
There are several objects/methods exported which you can import anytime and use to interact with the cookies or the choices that the user made.

- config: PlxCookieConfig
  - Exports the config that is set.
- setConfig(config: PlxCookieConfig)
  - Change the default configuration by specifying a new config object.
- validate()
  - Validates the current config.
- accept(suppliers: Array<string>)
  - Accept the cookie with an array of suppliers.
- acceptAll()
  - Accepts all suppliers.
- acceptNecessary()
  - Accepts all necessary suppliers.
- getAcceptedSuppliers()
  - Gets the cookie value and returns an array with the accepted suppliers.
- hasSavedPreferences()
  - Checks if the cookie is set.
- isAccepted(supplier: string)
  - Returns a boolean value.
- getStoredHash()
  - Gets the hash* that is stored at the end of the cookie string.
- onSave(callback: Function)
  - Add a callback function that will be excecuted when the user saves the cookie.
- onAccept(supplier: string, callback: (acceptedSuppliers: string[]) => void, getInitialValue: boolean) 
  - Add a callback function that will be excecuted when the user accepts the cookie.
- getData(force?: boolean)
  - Fetches and returns the data from Umbraco.
- getCategories()
  - Fetches the data from Umbraco and returns the cookie categories.
- getSuppliers()
  - Returns an array of cookie suppliers from Umbraco.
- getHash()
  - Fetches and returns a hash of the current cookie settings from Umbraco.
- getHash()
  - Fetches and returns the cookie text from Umbraco.
- getHistory()
  - Returns the history that is stored in the localstorage as an object.

\* Hash: is used to detect supplier changes in Umbraco. Whenever the cookie values are changed in Umbraco, a new hash is generated. *This feature is disabled by default since version 2.1.0, updated in 2.2.0 and can be enabled by setting config.useHash.*


### Example

```javascript
import { getAcceptedSuppliers } from '@perplex-digital/athlon-cookie-bar';

const acceptedSuppliers = getAcceptedSuppliers();
if(acceptedSuppliers.includes('youtube')) {
  // Load YouTube.
  console.log("YouTube loaded");
}
```

### Config (PlxCookieConfig)

```javascript
type PlxCookieConfig = {
  cookieName: string;
  cookieExpirationInDays: number;
  cookieDomain: string;
  historyKey: string;
  baseUrl: string;
  umbraconodeid: string;
  culture: string | null;
  useHash?: boolean;
}

// Default config:
const defaultConfig: PlxCookieConfig = {
  cookieName: 'PerplexCookieConsent',
  cookieExpirationInDays: 365,
  cookieDomain: window.location.hostname,
  historyKey: 'PerplexCookieConsent',
  baseUrl: 'https://umbraco.athlon.com/umbraco/api/cookies',
  umbraconodeid: '',
  culture: null,
  useHash: false,  
}
```
## Styling

Styling can be overriden by using CSS custom properties. For example you can do this in you CSS:

```css
athlon-cookie-bar {
  --plx-cookie-bar-bg: #ececec;
  --plx-cookie-bar-max-width: 2200px;
  --plx-cookie-bar-layout-padding: 4rem;
}

@media screen and (min-width: 48em) {
  athlon-cookie-bar {
    --plx-cookie-bar-layout-padding: 8rem;
  }
}
```

### REM values

The main Athlon sites have their root(html) font-size scaled down to make 1rem equal to 10px. This cookie component uses mainly REM-values. If you would like to change that to pixels, we would advise you to override the following CSS custom properties.

```css
athlon-cookie-bar {
  /* Button */
  --plx-button-font-size: 1.6rem;
  --plx-button-icon-size: 1.8rem;
  --plx-button-padding: 1.7rem 3rem;
  --plx-button-min-width: 20rem;

  /* Cookie bar */
  --plx-cookie-bar-layout-padding: 4rem;

  /* Cookie settings */
  --plx-overlay-margin: 8rem auto 6rem;
  --plx-overlay-close-spacing: 2rem;
  --plx-overlay-close-size: 3rem;
  --plx-overlay-close-icon-size: 2rem;
  --plx-cookie-settings-panel-width: 64rem;
  --plx-cookie-settings-panel-padding: 8rem 4rem 4rem;
  --plx-cookie-settings-tab-font-size: 1.8rem;
  --plx-cookie-settings-tab-font-weight: 600;
  --plx-cookie-settings-tab-padding: 1.4rem 0;
  --plx-cookie-settings-category-font-size: 2.4rem;
  --plx-cookie-settings-font-size: 18px;
  --plx-cookie-settings-supplier-gap: 0.5rem 0;
  --plx-cookie-settings-button-icon-size: 1.8rem;
  --plx-cookie-form-toggle-height: 3rem;
  --plx-cookie-form-toggle-border-width: 1px;
}
@media screen and (min-width: 80em) {
  :host {
    --plx-cookie-bar-layout-padding: 4rem 8rem;
    --plx-cookie-settings-panel-padding: 8rem;
  }
}
@media screen and (min-width: 120em) {
  :host {
    --plx-cookie-bar-layout-padding: 4rem 16rem;
  }
}
```