Skip to content

Commit

Permalink
Docs: Extend examples to showcase more features #CCM-20
Browse files Browse the repository at this point in the history
  • Loading branch information
OndraM committed Nov 9, 2021
1 parent 67febaa commit de1a0f2
Show file tree
Hide file tree
Showing 7 changed files with 435 additions and 55 deletions.
58 changes: 30 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,25 +27,24 @@ window.addEventListener('load', function () {
</script>
```

This will load the plugin from CDN and initialize the plugin with default settings. See [examples/index.html](examples/index.html).
This will load the plugin from CDN and initialize the plugin with default settings.
[👀 See example](https://lmc-eu.github.io/cookie-consent-manager/examples/).

## Use default web font, or not?

If you are going to use the plugin with the default theme, you may also want to
load default Spirit web font which is used by the plugin:
If you are going to use the plugin with the default theme, you may also want to load default Spirit web font
which is used by the plugin:

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap">
```

If Inter font is not provided (or installed in user's system), all texts in
cookie consent UI default to whatever current `font-family` is set to. As you
cannot predict what fonts are available on user's side, and because this
behavior may change in future versions of Spirit Design Tokens, we encourage you
either to load the default web font as shown above, or to explicitly specify
the desired font yourself (head to [Theming](#theming) to see how).
If Inter font is not provided (or installed in user's system), all texts in cookie consent UI default to whatever
current `font-family` is set to. As you cannot predict what fonts are available on user's side, and because this
behavior may change in future versions of Spirit Design Tokens, we encourage you either to load the default web font
as shown above or to explicitly specify the desired font yourself (head to [Theming](#theming) to see how).

## Loading the plugin

Expand Down Expand Up @@ -183,6 +182,8 @@ initLmcCookieConsentManager(
);
```
[👀 See extended configuration example](https://lmc-eu.github.io/cookie-consent-manager/examples/configuration.html)
## Configuration options
| Option | Type | Default value | Description |
Expand Down Expand Up @@ -212,6 +213,8 @@ Each configured callback receives two params:
| `onFirstAcceptOnlyNecessary`| Right after only necessary cookies are just accepted by the user |
| `onFirstAccept` | Right after any consent is just accepted by the user |
[👀 See callbacks example](https://lmc-eu.github.io/cookie-consent-manager/examples/callbacks.html)
## Theming
### With Spirit Design System
Expand All @@ -223,15 +226,13 @@ All you need to do is to add this plugin's SCSS to your Sass pipeline:
```scss
// my-project.scss
// Add this line anywhere you import other third-party CSS, possibly somewhere
// close to the end of your stylesheet as it contains CSS selectors with high
// specificity.
// Add this line anywhere you import other third-party CSS, possibly somewhere close
// to the end of your stylesheet as it contains CSS selectors with high specificity.
@use '@lmc-eu/cookie-consent-manager/LmcCookieConsentManager';
```
Now set up a [Sass load path] so the Sass compiler can find stylesheets located
in the `node_modules` directory (you will already have a path to your design
tokens there, as required by [Spirit Web]):
Now set up a [Sass load path] so the Sass compiler can find stylesheets located in the `node_modules` directory
(you will already have a path to your design tokens there, as required by [Spirit Web]):
```sh
# CLI command (possibly used in your npm scripts)
Expand Down Expand Up @@ -260,13 +261,15 @@ Or with webpack:
},
```
**Note:** `sass` v1.23 or higher is required to be able to compile the new Sass
modules syntax. You may need to migrate to [`sass`][sass] since all other Sass
compilers (and the old `@import` rule) are now [deprecated][sass modules].
**Note:** `sass` v1.23 or higher is required to be able to compile the new Sass modules syntax. You may need to migrate
to [`sass`][sass] since all other Sass compilers (and the old `@import` rule) are now [deprecated][sass modules].
### Without Spirit Design System
Following CSS custom properties are available for you to customize the UI:
<details>
<summary>Following CSS custom properties are available for you to customize the UI:</summary>
| CSS custom property | Description |
|---------------------------------------|---------------------------------------------------------|
Expand All @@ -290,24 +293,22 @@ Following CSS custom properties are available for you to customize the UI:
| `--lmcccm-btn-secondary-active-bg` | Secondary button background color in active state |
| `--lmcccm-btn-secondary-active-text` | Secondary button text color in active state |
Change their values to adjust cookie consent UI to match the design of your
site:
Change their values to adjust cookie consent UI to match the design of your site:
```css
:root {
--lmcccm-font-family: 'Open Sans', arial, sans-serif;
}
```
</details>
### Dark mode
Add `c_darkmode` CSS class to `<body>` to enable dark mode. It reuses [Spirit
Design Tokens], so if your project is built with Spirit, applying the
`c_darkmode` class is all you need to do and dark mode will work for you
out-of-the-box.
Add `c_darkmode` CSS class to `<body>` to enable dark mode. It reuses [Spirit Design Tokens], so if your project is
built with Spirit, applying the `c_darkmode` class is all you need to do and dark mode will work for you out-of-the-box.
If your project does _not_ use Spirit, you still may adjust exposed CSS custom
properties as described above, this time scoped to the `.c_darkmode` class:
If your project does _not_ use Spirit, you still may adjust exposed CSS custom properties as described above,
this time scoped to the `.c_darkmode` class:
```css
.c_darkmode {
Expand Down Expand Up @@ -357,7 +358,8 @@ yarn format:fix
#### Publishing package
Prepare release using `yarn release` on a local machine. Check the generated changelog and the bumped `package.json`. Then push to origin. Github [publish action](./github/worflows/publish.yaml) is then taking care of publishing package to [npmjs.com](https://npmjs.com/).
Prepare release using `yarn release` on a local machine. Check the generated changelog and the bumped `package.json`.
Then push to origin. Github [publish action](./github/worflows/publish.yaml) is then taking care of publishing package to [npmjs.com](https://npmjs.com/).
## License
Expand Down
117 changes: 117 additions & 0 deletions examples/callbacks.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Cookie Consent Manager – callbacks example</title>
<meta name="viewport" content="width=device-width, initial-scale=1">

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.7.0/font/bootstrap-icons.css">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap">
<script src="./functions.js" defer></script>

<link rel="stylesheet" href="../dist/LmcCookieConsentManager.css"><!-- You will load this from CDN instead -->
</head>
<body>

<header class="container mt-4">
<h1>LMC Cookie Consent Manager</h1>
</header>

<div class="container mt-4">
<ul class="nav nav-tabs">
<li class="nav-item">
<a class="nav-link" href=".">Basic example</a>
</li>
<li class="nav-item">
<a class="nav-link" href="./configuration.html">Extended configuration</a>
</li>
<li class="nav-item">
<a class="nav-link active" href="./callbacks.html">Callbacks</a>
</li>
<li class="nav-item">
<a class="nav-link" href="./theming.html">Theming</a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://github.com/lmc-eu/cookie-consent/" target="_blank">Documentation <i class="bi bi-box-arrow-up-right"></i></a>
</li>
</ul>
</div>

<main class="container mt-4">
<div class="row">
<div class="col">
<p class="lead">
This is an example of configurable callbacks.
</p>

<p>
<a href="" class="btn btn-warning" onclick="removeCookieAndReload();">
Remove <code>lmc_ccm</code> cookie and reload
</a>
</p>

<h3 class="mt-4">Callbacks</h3>

<div class="row">
<div class="col-md-6 col-xs-12">

<ul class="list-group">
<li class="list-group-item" id="callback-onAccept">onAccept</li>
<li class="list-group-item" id="callback-onAcceptAll">onAcceptAll</li>
<li class="list-group-item" id="callback-onAcceptOnlyNecessary">onAcceptOnlyNecessary</li>
<li class="list-group-item" id="callback-onFirstAccept">onFirstAccept</li>
<li class="list-group-item" id="callback-onFirstAcceptAll">onFirstAcceptAll</li>
<li class="list-group-item" id="callback-onFirstAcceptOnlyNecessary">onFirstAcceptOnlyNecessary</li>
</ul>
</div>
</div>
</div>
</div>
</main>

<script defer src="../dist/init.js"></script>
<script>
window.addEventListener('load', function () {
window.ccm = initLmcCookieConsentManager( // note we store cookieConsent instance in global window.ccm variable
{
autodetectLang: false, // do not detect language from the browser
defaultLang: 'en', // use 'en' language by default
onAccept: (cookie, cookieConsent) => { // any type of consent detected
markCallbackCalled('onAccept');
},
onAcceptAll: (cookie, cookieConsent) => { // consent for all cookies detected
markCallbackCalled('onAcceptAll');

if (cookieConsent.allowedCategory('functionality')) { // check for specific consent category
console.log('Consent for extended functionality given');
}
},
onAcceptOnlyNecessary: () => { // consent only for necessary cookies detected
markCallbackCalled('onAcceptOnlyNecessary');
// Note: you don't need to check this consent category before using "necessary" cookies
},
onFirstAccept: () => { // any consent was just given by the user
markCallbackCalled('onFirstAccept');
},
onFirstAcceptAll: () => { // consent with all was just given by the user
markCallbackCalled('onFirstAcceptAll');
},
onFirstAcceptOnlyNecessary: () => { // consent with only necessary cookies was just given by the user
markCallbackCalled('onFirstAcceptOnlyNecessary');
},
}
);
});

const markCallbackCalled = function (id) {
const element = document.getElementById(`callback-${id}`);
element.classList.add('list-group-item-success');
element.innerText += ' – called'
}
</script>

</body>
</html>
91 changes: 91 additions & 0 deletions examples/configuration.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Cookie Consent Manager – extended configuration example</title>
<meta name="viewport" content="width=device-width, initial-scale=1">

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.7.0/font/bootstrap-icons.css">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap">
<script src="./functions.js" defer></script>

<link rel="stylesheet" href="../dist/LmcCookieConsentManager.css">
</head>
<body>

<header class="container mt-4">
<h1>LMC Cookie Consent Manager</h1>
</header>

<div class="container mt-4">
<ul class="nav nav-tabs">
<li class="nav-item">
<a class="nav-link" href=".">Basic example</a>
</li>
<li class="nav-item">
<a class="nav-link active" href="./configuration.html">Extended configuration</a>
</li>
<li class="nav-item">
<a class="nav-link" href="./callbacks.html">Callbacks</a>
</li>
<li class="nav-item">
<a class="nav-link" href="./theming.html">Theming</a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://github.com/lmc-eu/cookie-consent/" target="_blank">Documentation <i class="bi bi-box-arrow-up-right"></i></a>
</li>
</ul>
</div>

<main class="container mt-4">
<div class="row">
<div class="col">
<p class="lead">
This is an example of extended configuration.
</p>

<p>
<a href="" class="btn btn-warning" onclick="removeCookieAndReload();">
Remove <code>lmc_ccm</code> cookie and reload
</a>
</p>
<p>

<h3 class="mt-4">Use cookieConsent instance</h3>

<p>
When <a href="https://github.com/lmc-eu/cookie-consent-manager#callbacks">callbacks</a> does not satisfy
your needs to conditional code execution, you can also store cookieConsent instance in a variable
and access it later when needed – see source code.
</p>

<p>
<a href="#" onclick="ccm.allowedCategory('analytics') ? console.log('Execute some analytics feature') : console.log('Do not execute analytics'); return false;">
Example link with conditional logic activated <code>onclick</code></a>
(see browser console – note difference with and without accepted consent)
</p>
</div>
</div>
</main>

<script defer src="../dist/init.js"></script>
<script>
window.addEventListener('load', function () {
window.ccm = initLmcCookieConsentManager( // note we store cookieConsent instance in global window.ccm variable
{
autodetectLang: false, // do not detect language from the browser
defaultLang: 'en', // use 'en' language by default
config: { // override default config of the underlying library, see https://github.com/orestbida/cookieconsent#all-available-options
delay: 500, // show cookie consent banner after 500ms
page_scripts: false, // disable third-party script management, see https://github.com/lmc-eu/cookie-consent-manager#third-party-scripts-loaded-via-script
},
}
);
});
</script>

</body>
</html>
6 changes: 6 additions & 0 deletions examples/functions.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
/**
* Global function to reset cookie for the examples only
*/
function removeCookieAndReload() {
document.cookie = `lmc_ccm=; Max-Age=0; path=/; domain=${location.hostname}`;
}
Loading

0 comments on commit de1a0f2

Please sign in to comment.