The Preferences Modal

Relevant source files

The following files were used as context for generating this wiki page:

• src/modules/GrantsInterface.ts
• src/modules/ConsentManager.ts
• src/styles.scss
• README.md
• src/bundle.ts
• src/index.ts

The Preferences Modal is a key UI component provided by the GrantsInterface module. It offers users a detailed view to manage their consent preferences for different categories of cookies or tracking scripts. Unlike the simple consent banner, the modal presents a table of all available consent categories, allowing for granular control. It is dynamically generated and injected into the DOM, providing a complete, ready-to-use interface for preference customization.

The modal is designed to work in tandem with the ConsentManager core, reading the defined categories and reflecting the current consent state (grants). User interactions within the modal directly call methods on the ConsentManager instance to update preferences, which are then persisted in a cookie.

Sources: src/modules/GrantsInterface.ts:1-290, README.md:129-135

Modal Architecture and Components

The Preferences Modal is constructed dynamically by the showModal method within the GrantsInterface class. It does not exist in the initial HTML of the page. When invoked, showModal assembles several HTML elements to create the modal's structure.

The main components are:

• Backdrop (.consent-manager--modal-backdrop): A full-screen, semi-transparent overlay that covers the page content and contains the modal container.
• Container (.consent-manager--modal-container): The main modal window that holds all other content.
• Header (.consent-manager--modal-header): Contains the modal title and a close button.
• Consent Table: A <table> element generated by the generateConsentTable method, which lists all consent categories.
• Footer (.consent-manager--modal-actions): Contains the "Accept All" and "Only required" action buttons.

Sources: src/modules/GrantsInterface.ts:221-279, src/styles.scss:69-129

Component Structure Diagram

This diagram illustrates the nested structure of the DOM elements that form the Preferences Modal.

Key UI Components

Component	CSS Class	Description	Source File
Backdrop	.consent-manager--modal-backdrop	Full-screen overlay. Clicking it closes the modal.	src/styles.scss:69-80
Container	.consent-manager--modal-container	The main dialog box for the modal.	src/styles.scss:82-90
Header	.consent-manager--modal-header	Top section with title and close button.	src/styles.scss:92-97
Title	.consent-manager--modal-title	The main heading of the modal.	src/styles.scss:99-102
Close Button	.consent-manager--modal-close	A '×' icon to dismiss the modal.	src/styles.scss:104-107
Actions Footer	.consent-manager--modal-actions	Footer section for global action buttons.	src/styles.scss:109-111
Accept Button	.consent-manager--modal-accept	Button to accept all non-required categories.	src/styles.scss:113-129
Reject Button	.consent-manager--modal-reject	Button to reject all non-required categories.	src/styles.scss:113-129

Sources: src/modules/GrantsInterface.ts:221-279, src/styles.scss:69-129

Display and Control

The visibility of the modal is controlled by two public methods in the GrantsInterface class: showModal() and hideModal().

• showModal(): This method first checks if a modal is already present in the DOM by querying for .consent-manager--modal-backdrop. If not, it proceeds to build the entire modal structure from scratch, including the header, the consent table (by calling generateConsentTable(true)), and the footer actions. It then appends the fully constructed modal to document.body.
• hideModal(): This method finds the modal backdrop element and removes it from the DOM, effectively hiding the modal.

The modal can be shown manually by calling gi.showModal(), or automatically when the "More options" button on the Consent Banner is clicked.

Sources: src/modules/GrantsInterface.ts:90-97, src/modules/GrantsInterface.ts:221-290, README.md:143-151

Modal Display Flow

The following diagram shows the logic flow for displaying the modal.

User Interaction and Data Flow

The Preferences Modal facilitates a reactive data flow between the user, the UI, and the core ConsentManager.

1. Initial State: When the modal is shown, the generateConsentTable method reads the categories from client.config.categories and the current grant statuses from client.grants to render the checkboxes in their correct state (checked/unchecked, enabled/disabled).
2. User Action: A user can interact with the modal in three ways:
   • Toggle a Category: Clicking a checkbox for a non-required category triggers a change event.
   • Accept All: Clicking the "Accept All" button.
   • Reject All: Clicking the "Only required" button.
3. State Update: Each action calls this.client.setGrant() with the appropriate parameters (e.g., a specific category ID and a boolean status, or '*' for all categories).
4. Persistence: The setGrant method in ConsentManager updates the grants object, dispatches update and grant/revoke events, and writes the new state to a browser cookie.
5. UI Feedback: Because the consent table is generated with autoUpdate = true, it registers an 'update' event listener on the ConsentManager instance. When setGrant dispatches this event, the listener checks if the updated category ID matches its own and updates the checked property of the corresponding checkbox. This ensures the UI stays in sync if grants are changed from another source.

Sources: src/modules/GrantsInterface.ts:153-219, src/modules/ConsentManager.ts:182-211

Sequence Diagram: Updating a Grant

This diagram shows the sequence of events when a user toggles a consent category checkbox in the modal.

Configuration and Customization

The text strings displayed in the modal can be customized during the GrantsInterface instantiation via the languageStrings configuration object. If no custom strings are provided, default English values are used.

languageStrings.modal Options

Property	Type	Default Value	Description
title	string	'Consent options'	The title displayed in the modal's header.
accept	string	'Accept All'	Text for the button that grants all optional categories.
reject	string	'Only required'	Text for the button that revokes all optional categories.

Sources: src/modules/GrantsInterface.ts:13-20, src/modules/GrantsInterface.ts:33-37

Example: Customizing Modal Text

import { GrantsInterface, ConsentManager } from 'consent-manager';

const consentManager = new ConsentManager({ /* ... config ... */ });

new GrantsInterface(consentManager, {
  languageStrings: {
    modal: {
      title: 'Your Privacy Choices',
      accept: 'Allow All Cookies',
      reject: 'Use Essential Cookies Only'
    }
  }
});

Sources: README.md:153-168, src/modules/GrantsInterface.ts:40-42

Summary

The Preferences Modal is a powerful, self-contained UI component for detailed consent management. It is created and managed by the GrantsInterface class, building its structure and content dynamically based on the configuration of a ConsentManager instance. Through a system of event listeners and method calls, it provides a reactive and intuitive experience for the end-user to view and control their consent choices, with all changes being persisted automatically. The modal's appearance and text can be customized to fit the branding of the host application.

Sources: src/modules/GrantsInterface.ts, src/modules/ConsentManager.ts, README.md