Recipe: Showing or Hiding Content

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 consent-manager library provides a dedicated module, DOMConnector, to dynamically modify the Document Object Model (DOM) based on user consent preferences. This allows developers to show, hide, or alter content and functionality, such as loading tracking scripts or displaying personalized elements, without writing custom JavaScript logic. The entire mechanism is declarative, using a set of data-* attributes on HTML elements.

The DOMConnector works in tandem with the core ConsentManager class. It listens for changes in consent grants and automatically updates the DOM to reflect the user's current choices. This provides a powerful and easy-to-implement solution for making web pages compliant with privacy requirements.

Sources: README.md, src/modules/DOMConnector.ts

Core Component: DOMConnector

The DOMConnector class is the central piece of this functionality. It is exported as a named export from the main package entry point.

Sources: src/index.ts:4, src/bundle.ts:4

Initialization

To use the DOMConnector, you must instantiate it with an active ConsentManager client instance.

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

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

new DOMConnector(consentManager);

Upon initialization, the DOMConnector's constructor performs two key actions:

1. It immediately calls its internal updateDOM() method to scan the document and apply consent-based attributes to all relevant elements.
2. It subscribes to the update event emitted by the ConsentManager instance, ensuring that updateDOM() is called again whenever a user's consent grant is changed.

Sources: src/modules/DOMConnector.ts:4-7, README.md:111-114

Initialization and Update Flow

The following diagram illustrates the lifecycle of the DOMConnector from instantiation to subsequent updates.

This diagram shows how DOMConnector initializes and then listens for update events from ConsentManager to re-evaluate the DOM.
Sources: src/modules/DOMConnector.ts:4-7

Declarative HTML Attributes

The DOMConnector identifies and manipulates elements using a specific set of data-* attributes. An element must have data-consent-manager to be considered.

Attribute	Description	Required	Example
data-consent-manager	A marker attribute that makes the element visible to the DOMConnector.	Yes	<div data-consent-manager>
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-categories="analytics,marketing"
data-cm-attribute	The name of the HTML attribute to set on the element when consent is granted.	Yes	data-cm-attribute="style"
data-cm-value	The value to assign to the attribute specified by data-cm-attribute.	Yes	data-cm-value="display: block;"
data-cm-inverted	An optional flag that inverts the logic. If present, the attribute is applied when consent is not granted for any of the specified categories.	No	<p data-cm-inverted>

Sources: README.md:116-125, src/modules/DOMConnector.ts:10, 31, 36

Internal Logic and Flow

The core logic resides in the updateDOM and isElementGranted methods within the DOMConnector class.

updateDOM() Method

This method is the engine that drives the DOM modifications.

1. It selects all HTML elements in the document that have the [data-consent-manager] attribute.
2. It iterates over each found element.
3. For each element, it checks for the presence of data-cm-attribute and data-cm-value, logging a warning if they are missing.
4. It calls isElementGranted(el) to determine if the element's consent conditions are met.
5. If isElementGranted() returns true, it uses setAttribute() to apply the specified attribute and value.
6. If it returns false, it uses removeAttribute() to remove the specified attribute, effectively reverting the element to its default state.

Sources: src/modules/DOMConnector.ts:28-46

isElementGranted() Method

This private method contains the decision logic for a single element.

1. It reads the data-cm-categories attribute, splitting the comma-separated string into an array of category IDs.
2. It iterates through this array of required categories. For each category, it checks the this.client.grants object (from the ConsentManager instance) to see if its value is true.
3. If any required category is granted, the check succeeds, and a local isGranted flag is set to true.
4. Finally, it checks for the presence of the data-cm-inverted attribute. If present, it returns the opposite of the isGranted flag. Otherwise, it returns the isGranted flag as is.

Sources: src/modules/DOMConnector.ts:9-26

Sequence of Operations

The following sequence diagram shows the interaction between the ConsentManager and DOMConnector when a user's consent is updated via the UI.

This diagram details the event-driven flow from a user action in the UI to the final DOM manipulation by DOMConnector.
Sources: src/modules/DOMConnector.ts:5, src/modules/ConsentManager.ts:168-175, src/modules/GrantsInterface.ts:74-76

Usage Examples

The following examples from the project's documentation illustrate how to use the data attributes to achieve common 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 if 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:128-134

Show Content When Consent Is Not Given

This example uses the data-cm-inverted flag to show a paragraph of text only when the user has not consented to the experience category. The style attribute is added to override the default display: none.

<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:137-153

Summary

The DOMConnector module offers a declarative and automated way to align a web page's content and behavior with user consent preferences. By leveraging simple data-* attributes, developers can conditionally load scripts, show or hide elements, and modify element attributes without writing any custom event handling or DOM manipulation code. This feature is a cornerstone of the consent-manager library, providing a practical and efficient tool for building privacy-conscious user experiences.

Sources: README.md:108-110, src/modules/DOMConnector.ts