Programmatic UI Control

Relevant source files

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

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

The consent-manager library provides two distinct modules for programmatically controlling the user interface based on consent preferences: GrantsInterface and DOMConnector. The GrantsInterface offers ready-to-use UI components, such as a consent banner and a preferences modal, which can be controlled via its methods. This is ideal for quickly implementing a standard consent UI.

Alternatively, the DOMConnector module provides a declarative approach. By adding specific data- attributes to HTML elements, developers can control their attributes and visibility based on the user's consent status without writing custom JavaScript logic. Both modules are built upon the core ConsentManager class, which handles the underlying state management and cookie interactions. These modules can be imported for use in a bundled application or used directly from a script tag where they are exposed on the window object.

Sources: README.md, src/index.ts:4-5, src/bundle.ts:4-8

GrantsInterface Module

The GrantsInterface class is responsible for generating and managing pre-built UI elements for user consent interaction. It creates a cookie banner and a detailed preferences modal, which are automatically linked to a ConsentManager instance to reflect and update consent states.

Sources: src/modules/GrantsInterface.ts, README.md:121-126

Initialization and Configuration

An instance of GrantsInterface is created by passing a ConsentManager instance and an optional configuration object.

import ConsentManager from 'consent-manager';
import { GrantsInterface } from 'consent-manager';
import 'consent-manager/dist/consent-manager.css';

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

// Initialize with default behavior (auto-shows banner)
const gi = new GrantsInterface(consentManager);

// Initialize with custom behavior (manual control)
const gi_manual = new GrantsInterface(consentManager, { autoShow: false });

Sources: README.md:123-126, 134-135, src/modules/GrantsInterface.ts:43-49

By default, if the user has not yet customized their preferences (client.isCustomized is false), the consent banner is shown automatically. This behavior can be disabled by setting autoShow to false in the configuration.

The following diagram shows the initialization flow.

Configuration Options

The GrantsInterface constructor accepts a configuration object to customize its behavior and displayed text.

| Option | Type | Description | Default Value - |
| autoShow | boolean | If true, the banner is shown on initialization if consent has not been customized. | true - |
| languageStrings | object | An object containing strings for the banner and modal UI. Any unspecified strings will use the default values. See GrantsInterfaceConfig for the full structure. | { banner: { infoText: '...', accept: '...', ... }, modal: { ... } } |

Sources: src/modules/GrantsInterface.ts:6-20, 29-41

Public Methods

The GrantsInterface provides several public methods to manually control the UI elements.

Method	Description
showBanner()	Creates and displays the consent banner in the DOM if it doesn't already exist. It also attaches an event listener to hide the banner when consent is customized.
hideBanner()	Removes the consent banner element from the DOM.
showModal()	Creates and displays the preferences modal, which includes a detailed consent table.
hideModal()	Removes the preferences modal from the DOM.
generateConsentTable()	Generates and returns an HTMLTableElement containing the consent categories. An optional boolean argument autoUpdate makes the table reactive to consent changes.

Sources: src/modules/GrantsInterface.ts:51-110, 203-210, 269-275, README.md:137-148, 161-167

UI Components

Consent Banner

The banner is a fixed-position element that appears at the bottom of the screen. It is created by showBanner() and has the CSS class .consent-manager--banner-wrapper.

It contains:

• An informational text.
• An "Accept All" button (.consent-manager--banner-accept): Grants all categories by calling client.setGrant('*', true).
• A "Only required" button (.consent-manager--banner-reject): Revokes all non-required categories by calling client.setGrant('*', false).
• A "More options" button (.consent-manager--banner-more): Shows the preferences modal and hides the banner.

The following sequence diagram illustrates the interaction when a user clicks the "More options" button.

Preferences Modal

The modal is a centered overlay created by showModal(). The root element is a div with the class .consent-manager--modal-backdrop. It contains:

• A header with a title and a close button.
• A body containing the consent table generated by generateConsentTable(true).
• A footer with "Accept All" and "Only required" buttons, similar to the banner.

Closing the modal can be done by clicking the close button or the backdrop.

Sources: src/modules/GrantsInterface.ts:203-267, src/styles.scss:65-115

generateConsentTable() Method

This method dynamically builds an HTML table (.consent-manager--table) from the categories defined in the ConsentManager configuration.

• Each row represents a consent category.
• It includes a checkbox (.consent-manager--table-toggle) and labels for the category name and description.
• Checkboxes for required categories are disabled and checked.
• For optional categories, a change event listener is added to the checkbox, which calls client.setGrant(categoryId, isChecked).
• If autoUpdate is set to true, it also registers a listener on the ConsentManager's update event to keep the checkbox state synchronized with the client.grants.

This flow chart shows how a table row is generated for a single category.

DOMConnector Module

The DOMConnector offers a declarative way to manipulate the DOM based on consent grants. Instead of writing imperative JavaScript to show or hide elements, you can add data- attributes to your HTML, and DOMConnector will handle the logic.

Sources: src/modules/DOMConnector.ts, README.md:99-103

Initialization

To use it, instantiate DOMConnector with a ConsentManager instance. The connector will perform an initial DOM update and then subscribe to the ConsentManager's update event to react to any changes in consent.

import { DOMConnector } from 'consent-manager';

new DOMConnector(consentManager);

Sources: src/modules/DOMConnector.ts:4-7, README.md:106-108

Declarative data- Attributes

DOMConnector scans for elements with the data-consent-manager attribute and modifies them based on the other data-cm-* attributes present.

Attribute	Description	Example
data-consent-manager	A required marker attribute that identifies an element to be managed by DOMConnector.	data-consent-manager
data-cm-categories	A comma-separated list of category IDs. The element is considered "enabled" if consent is granted for at least one of these categories.	data-cm-categories="analytics"
data-cm-inverted	If present, inverts the logic. The element is "enabled" if consent is not granted for any of the specified categories.	data-cm-inverted
data-cm-attribute	The name of the HTML attribute to set on the element when it is "enabled".	data-cm-attribute="src"
data-cm-value	The value to set for the attribute specified by data-cm-attribute.	data-cm-value="script.js"

Sources: src/modules/DOMConnector.ts:10-12, 30-35, README.md:110-116

Logic Flow

The core logic resides in the updateDOM and isElementGranted methods.

1. updateDOM queries the document for all elements with [data-consent-manager].
2. For each element, it checks for the presence of data-cm-attribute and data-cm-value.
3. It calls isElementGranted to determine if the element's conditions are met.
4. isElementGranted reads the data-cm-categories, checks them against client.grants, and considers the data-cm-inverted flag.
5. If isElementGranted returns true, updateDOM sets the attribute (el.setAttribute(attr, value)).
6. If it returns false, updateDOM removes the attribute (el.removeAttribute(attr)).

The following diagram illustrates this process.

Usage Example

To conditionally load an analytics script, you can use DOMConnector like this. The src attribute will only be added to the script tag if the user has granted consent for the analytics category.

<script
  data-consent-manager
  data-cm-categories="analytics"
  data-cm-attribute="src"
  data-cm-value="https://analytics-provider.com/script.js"
></script>

Sources: README.md:118-124