Initial work on rebuild

duncanmcclean · Apr 20, 2024 · d5caac0 · d5caac0
1 parent 83b4333
commit d5caac0
Show file tree

Hide file tree

Showing 16 changed files with 398 additions and 433 deletions.
diff --git a/config/cookie-notice.php b/config/cookie-notice.php
@@ -7,14 +7,15 @@
     | Cookie
     |--------------------------------------------------------------------------
     |
-    | It's ironic, but this addon uses cookies to store if a user has consented
-    | to cookies or not, and which ones they've consented to. Don't worry
-    | though, no cookie is stored if the user doesn't consent.
+    | It's ironic, but this addon uses cookies to determine which consent groups
+    | a user has consented to. Configure the name & expiry of the cookie here.
     |
     */
 
     'cookie_name' => 'COOKIE_NOTICE',
 
+    'cookie_expiry' => 14,
+
     /*
     |--------------------------------------------------------------------------
     | Consent Groups
@@ -25,18 +26,17 @@
     |
     */
 
-    'groups' => [
-        'Necessary' => [
-            'required' => true,
-            'toggle_by_default' => true,
-        ],
-        'Statistics' => [
-            'required' => false,
-            'toggle_by_default' => false,
+    'consent_groups' => [
+        [
+            'name' => 'Necessary',
+            'handle' => 'necessary',
+            'enable_by_default' => true,
         ],
-        'Marketing' => [
-            'required' => false,
-            'toggle_by_default' => false,
+        [
+            'name' => 'Analytics',
+            'handle' => 'analytics',
+            'description' => 'These cookies are used to provide us with analytics on which content visitors read, etc.',
+            'enable_by_default' => false,
         ],
     ],
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -2,7 +2,7 @@
 title: Configuration
 ---
 
-During installation, you'll publish a configuration file for Cookie Notice to `config/cookie-notice.php`. The contents of said file look like this:
+During the installation process, you'll have published a configuration file to `config/cookie-notice.php`. The contents of the file look like this:
 
 ```php
 <?php
@@ -14,14 +14,15 @@ return [
     | Cookie
     |--------------------------------------------------------------------------
     |
-    | It's ironic, but this addon uses cookies to store if a user has consented
-    | to cookies or not, and which ones they've consented to. Don't worry
-    | though, no cookie is stored if the user doesn't consent.
+    | It's ironic, but this addon uses cookies to determine which consent groups
+    | a user has consented to. Configure the name & expiry of the cookie here.
     |
     */
 
     'cookie_name' => 'COOKIE_NOTICE',
 
+    'cookie_expiry' => 14,
+
     /*
     |--------------------------------------------------------------------------
     | Consent Groups
@@ -32,23 +33,40 @@ return [
     |
     */
 
-    'groups' => [
-        'Necessary' => [
-            'required' => true,
-            'toggle_by_default' => true,
-        ],
-        'Statistics' => [
-            'required' => false,
-            'toggle_by_default' => false,
+    'consent_groups' => [
+        [
+            'name' => 'Necessary',
+            'handle' => 'necessary',
+            'enable_by_default' => true,
         ],
-        'Marketing' => [
-            'required' => false,
-            'toggle_by_default' => false,
+        [
+            'name' => 'Analytics',
+            'handle' => 'analytics',
+            'description' => 'These cookies are used to provide us with analytics on which content visitors read, etc.',
+            'enable_by_default' => false,
         ],
     ],
 
 ];
 ```
 
-- `cookie_name` defines the name of the cookie you wish to store the users' cookie preferences.
-- `groups` is an array of consent groups. Feel free to update them however you want. The key is the name of the group, which will be displayed to the user. `required` defines whether the user is absolutly required to accept cookies for that group. `toggle_by_default` will automatically check the checkbox on the consent notice, however the user will be able to uncheck it if they want.
+## `cookie_name`
+
+The `cookie_name` config option determines the name of the cookie used to store the user's cookie preferences.
+
+## `cookie_expiry`
+
+The `cookie_expiry` config option determines how long the user's cookie preferences should be kept for before re-prompting for consent.
+
+The default is 14 days.
+
+## `consent_groups`
+
+The `consent_groups` config option is an array containing your consent groups. You should change these as needed.
+
+### Supported config options
+
+* `name` - This name will be displayed to the user.
+* `handle` - The handle will be used as a unique identifier for this consent group.
+* `description` - This description is optional. It'll be displayed to the user, alongside the name.
+* `enable_by_default` - This determines whether the consent group will be enabled by default. The user will still be able to disable it if they wish.
diff --git a/docs/customization.md b/docs/customization.md
@@ -0,0 +1,54 @@
+---
+title: Customization
+---
+
+The Cookie Notice addon was built with customization in mind. Although, a cookie consent widget is provided out-of-the-box, you can also build your own widget without any style limitations.
+
+## Custom Widget
+
+To create your own widget, you'll need to create your own view. Here's the boilerplate you need to build your own widget:
+
+```html
+<div id="cookie-notice" class="relative" style="z-index: 999">
+    <div class="fixed bottom-2 right-2 bg-white p-4">
+        <h2>This site uses cookies.</h2>
+        <ul>
+            {{ consent_groups }}
+                <li>
+                    <input type="checkbox" name="group-{{ handle }}">
+                    <label for="group-{{ handle }}">{{ name }}</label>
+                    {{ if description }}
+                        <span>{{ description }}</span>
+                    {{ /if }}
+                </li>
+            {{ /consent_groups }}
+        </ul>
+        <button type="button" data-save-preferences>{{ trans key="Save Preferences" }}</button>
+    </div>
+</div>
+
+<script>
+    document.addEventListener('DOMContentLoaded', () => {
+        window.CookieNotice.boot(
+            document.getElementById('cookie-notice'),
+            JSON.parse('{{ config | to_json }}')
+        );
+    });
+</script>
+```
+
+Next, provide the `view` parameter to the `{{ cookie_notice }}` tag to ensure the Cookie Notice tag uses the correct view:
+
+```antlers
+{{ cookie_notice view="components/cookie_notice" }}
+```
+
+## "Update Cookie Preferences" button
+
+Out of the box, there's no way for users to update their preferences after initially providing consent.
+
+However, it's very easy to setup. Simply add the `data-show-cookie-notice-widget` attribute to the element you wish to trigger the widget and it'll show.
+
+```html
+<button type="button" data-show-cookie-notice-widget>Update cookie preferences</button>
+```
diff --git a/docs/events.md b/docs/events.md
@@ -2,56 +2,40 @@
 title: Events
 ---
 
-Cookie Notice will emit events when it's initially loaded on a page or where a consent group is consented/revoked by the user. This is the best way of catching whether a user has consented to a specific group or not.
+Whenever the page loads or the user changes their consent preferences, Cookie Notice will dispatch events so you can run the relevant scripts.
 
-> Note: Your JavaScript will need to come after Cookie Notice's own JavaScript, otherwise it won't work.
+> **Note:**
+> Make sure your JavaScript is *after* the `{{ cookie_notice:scripts }}` tag.
 
-## Initial load
-
-The `loaded` event will be emitted once Cookie Notice has loaded. It'll give you an array containing the consent groups the user has consented to. You'll probably only need to check the `slug`:
+## `accepted`
+**Dispatched when the user provides their consent to a consent group. Also dispatched when loading the page, with the user's existing preferences.**
 
 ```html
 <script>
-  cookieNotice.on('loaded', (groups) => {
-      if (groups.find(group) => group.slug === 'group_statistics') {
-          // Load Google Analytics... (or something else...)
-      }
-
-      if (groups.find(group) => group.slug === 'group_marketing') {
-          // Load Facebook Pixel... (or something else...)
-      }
-  })
+window.CookieNotice.on('accepted', (consentGroup) => {
+    //
+});
 </script>
 ```
 
-## Consented to group
-
-The `consented` event will be emitted when the user has consented to a consent group. It'll give you an object containing information on the group the user has consented to.
+## `declined`
+**Dispatched when the user removes their consent from a consent group. Also dispatched when loading the page, with the user's existing preferences.**
 
 ```html
 <script>
-  cookieNotice.on("consented", (group) => {
-    if (group.slug === "group_marketing") {
-      // Load Facebook Pixel...
-    }
-
-    // ...
-  });
+window.CookieNotice.on('declined', (consentGroup) => {
+    //
+});
 </script>
 ```
 
-## Revoked group
-
-The `revoked` event will be emitted when the user has revoked consent for a consent group. It'll give you an object containing information on the group the user has revoked.
+## `preferences_updated`
+**Dispatched when the user updates their consent preferences.**
 
 ```html
 <script>
-  cookieNotice.on("revoked", (group) => {
-    if (group.slug === "group_marketing") {
-      // Stop Facebook Pixel from tracking the user...
-    }
-
-    // ...
-  });
+window.CookieNotice.on('preferences_updated', (preferences) => {
+    //
+});
 </script>
 ```
diff --git a/docs/examples/checking-consent-with-alpine-js.md b/docs/examples/checking-consent-with-alpine-js.md
diff --git a/docs/examples/google-tag-manager.md b/docs/examples/google-tag-manager.md