npm package: @makemewin/proposal.js
Description: Lightweight Cookie consent manager (EU GDPR Compliant) with convenient APIs. In Vanilla, for maximum compatibility.
Author: Simon Lamellière
Latest version: 1.1.0

# Proposal.js

Proposal.js is a lightweight cookie consent manager (EU GDPR Compliant) with convenient APIs. 
Available in Vanilla (or ES Module), for maximum compatibility.

Warning : this is still a beta software. Feel free to report issues, or participate to development.

More to come :
- richer documentation
- tests
- servics groups

### UI

<img width="1139" alt="Capture d’écran 2021-04-14 à 15 12 53" src="https://user-images.githubusercontent.com/4090813/114715985-e8d38000-9d33-11eb-9c73-742722fdfa8a.png">
<img width="1154" alt="Capture d’écran 2021-04-14 à 15 12 43" src="https://user-images.githubusercontent.com/4090813/114716000-ec670700-9d33-11eb-8edc-85fcb876cf34.png">

### Configuration

```js
{
    messages: {}, // allow you to override default translations
    coookieDuration: 365, // specify the number of days we will keep the user's choices
    cookieName: 'proposal-js', // specify the cookie name where this configuration will be saved
    services: [], // specify your services (check Service Template)
    policyUrl: null // specify your data policy URL
},
```

### Service Template

```js
{
    // a unique identifier, alphanumerical
    'code': 'default',
    // the name of your tag / service that creates cookies
    'name': 'Name of the service',
    // a description for this service
    'description': null,
    // specify if these cookies are mandatory/required (eg. technical cookies : session, etc)
    'required': false,
    // render HTML at the end of body when allow/deny this service
    'allowHtml': null,
    'denyHtml': null,
    // execute a Callback function when allow/deny this service
    'allowCallback': function(service) {
        // code to execute when user accepts this (or all) cookie(s)
    },
    'denyCallback': function(service) {
        // code to execute when user denies this (or all) cookie(s)
    }
}
```

### Example

```js
// Init Proposal
proposal.init({
    // Your Policy URL
    'policyUrl': 'https://makemewin.net/fr/conditions_d_utilisation/',
    // List your services (check Service Template)
    'services': [
        {
            'required': true,
            'code': 'technical',
            'name': '👩‍💻 Technical Cookies',
            'description': 'Used to store your session, analyze our product performances (New Relic)',
            'allowHtml': '<!-- WILL INJECT THIS IN BODY -->',
            'denyHtml': '<!-- WILL INJECT THIS IN BODY -->',
            'allowCallback': function (service) {
                console.log(service.code + ' JS executed (allow)');
            },
            'denyCallback': function (service) {
                console.log(service.code + ' JS executed (deny)');
            }
        },
        {
            'code': 'analytics',
            'name': '📊 Analytics Cookies',
            'description': 'Used to quantize blabla',
            'allowCallback': function (service) {
                console.log(service.code + ' JS executed (allow)');
            },
            'denyCallback': function (service) {
                console.log(service.code + ' JS executed (deny)');
            }
        },
        {
            'code': 'social',
            'name': '🍺 Social Network',
            'description': 'Use to track you down',
            'allowCallback': function (service) {
                console.log(service.code + ' JS executed (allow)');
            },
            'denyCallback': function (service) {
                console.log(service.code + ' JS executed (deny)');
            }
        }
    ],
    // Customize your messages
    'messages': {
        '___YES___': 'Allow',
        '___NO___': 'Deny',
        '___HEADER___': '🍪 Cookie Consent 🥰',
        '___MESSAGE___': 'This website allows you to choose what cookies you want to enable.<br/>You can either allow all, deny all, or customize cookies.<br/>',
        '___ACCEPT_ALL___': 'Allow all',
        '___DENY_ALL___': 'Deny all',
        '___SAVE_SELECTION___': 'Save selection',
        '___CONFIGURE___': 'Customize',
        '___LEGAL___': 'Please note that there are often technical cookies that cannot be disabled.<br/>See our <a href="###LINK###" target="_blank">Privacy Policy</a>',
    }
});
```

### Events

```js
// When proposaljs is loaded and ready
document.addEventListener('prjs.ready', function (e) {
    // do something...
    console.log(e.detail); // some details about user's choices
});

// When selection is saved
document.addEventListener('prjs.saveSelection', function (e) {
    // do something...
});

// When user choose to allow all
document.addEventListener('prjs.allowAll', function (e) {
    // do something...
});

// When user choose to deny all
document.addEventListener('prjs.denyAll', function (e) {
    // do something...
});

// When the user allow or deny a service
document.addEventListener('prjs.decision', function (e) {
    // do something...
    console.log(e.detail); // some details about user's choices
    // e.detail = { 
    //      'service': {},
    //      'code': service.code,
    //      'decision': 'allow|deny'
    // }
});

// When the configuration is over, and the callbacks are executed
document.addEventListener('prjs.terminate', function (e) {
    // do something...
    console.log(e.detail); // some details about user's choices
});

// When cookie modal is shown
document.addEventListener('prjs.shown', function (e) {
    // do something...
});

// When cookie modal is hidden
document.addEventListener('prjs.hidden', function (e) {
    // do something...
});

```


### Usage

Common usage:

```html
<script src="https://cdn.jsdelivr.net/npm/js-cookie@rc/dist/js.cookie.min.js"></script>
<link rel="stylesheet" href="/path/to/proposaljs/proposaljs.css">
<script src="/path/to/proposaljs/proposal.js"></script>
```

Usage with Yarn / Encore / ES Module
```js
import proposal from '@makemewin/proposal.js';
import '@makemewin/proposal.js/proposaljs.css';
global.proposal = proposal;
```