DOMConnector: Declarative Integration

Relevant source files

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

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

The DOMConnector module provides a way to modify the Document Object Model (DOM) based on user consent preferences without writing custom JavaScript logic. It acts as a bridge between the core ConsentManager and the HTML, using a set of data-* attributes to declaratively control element attributes. This allows for features like conditional script loading or showing/hiding elements based on whether a user has granted consent for specific categories.

Sources: README.md:116-118, src/modules/DOMConnector.ts

Initialization

To use the DOMConnector, it must be instantiated with an active ConsentManager instance. The DOMConnector is exported as a named export from the main package entry point.

Sources: src/index.ts:4, README.md:120-123

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

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

new DOMConnector(consentManager);

Sources: README.md:120-123

Upon initialization, the DOMConnector performs two key actions:

1. It immediately scans the DOM and applies changes based on the current consent state by calling updateDOM().
2. It subscribes to the update event of the ConsentManager instance. This ensures that any subsequent changes to consent grants will automatically trigger a re-evaluation and update of the connected DOM elements.

The following diagram illustrates the initialization sequence.

This diagram shows the constructor logic for DOMConnector.
Sources: src/modules/DOMConnector.ts:4-7

Declarative Attributes

DOMConnector identifies and manipulates elements using a specific set of data-* attributes. An element must have the data-consent-manager attribute to be recognized by the connector.

Attribute	Description	Required
data-consent-manager	A marker attribute that makes the DOMConnector aware of the element.	Yes
data-cm-categories	A comma-separated list of consent category IDs. The element is considered "granted" if consent is given for at least one of these categories.	Yes
data-cm-attribute	The name of the HTML attribute that will be set on the element when its state is "granted".	Yes
data-cm-value	The value to be assigned to the attribute specified by data-cm-attribute.	Yes
data-cm-inverted	An optional attribute that inverts the logic. If present, the data-cm-attribute is applied when consent is not granted for the specified categories.	No

Sources: README.md:125-135, src/modules/DOMConnector.ts:9-29, 36-45

Core Logic

The core functionality revolves around the updateDOM method, which is triggered on initialization and whenever consent grants change.

DOM Update Flow

The updateDOM method queries the entire document for elements with the data-consent-manager attribute. For each element found, it validates that the necessary data-cm-attribute and data-cm-value attributes are present. It then calls isElementGranted to determine the element's status and either sets or removes the target attribute accordingly.

This flowchart shows the process executed by the updateDOM method.

Grant Check Logic

The isElementGranted method contains the logic for determining if an element should be "active" based on consent. It reads the categories from data-cm-categories, checks them against the grants property of the ConsentManager instance, and considers the data-cm-inverted flag.

This flowchart details the decision-making process within isElementGranted.

Usage Examples

The declarative nature of DOMConnector simplifies common consent-related tasks.

Conditionally Load a Script

This example shows how to load an analytics script only if the user has consented to the analytics category. The src attribute is only added to the script tag after consent is granted.

<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:140-146

Show an Element if Consent is Not Given

Using the data-cm-inverted attribute, you can show a message or element when consent is missing. In this example, the paragraph is hidden by default and the style="display: block;" attribute is added only if the experience category has not been granted.

<style>
  p {
    display: none;
  }
</style>

<p
  data-consent-manager
  data-cm-categories="experience"
  data-cm-inverted
  data-cm-attribute="style"
  data-cm-value="display: block;"
>
  Please consent to the use of cookies to use this feature!
</p>

Sources: README.md:150-166

Conclusion

The DOMConnector is a powerful utility within the consent-manager ecosystem that enables developers to manage DOM elements based on consent status in a purely declarative way. By abstracting the logic into HTML data-* attributes, it reduces the need for custom event handling and JavaScript, leading to cleaner and more maintainable code for implementing consent-dependent features.

Sources: README.md:116-118, src/modules/DOMConnector.ts