Managing Consent (setGrant)
Relevant source files
The following files were used as context for generating this wiki page:
The setGrant method is the primary mechanism for updating user consent preferences within the consent-manager library. It provides a centralized function to grant or revoke consent for specific categories of cookies or services. When called, it not only updates the internal state of the ConsentManager instance but also persists these changes to a browser cookie and notifies other parts of the application, such as the UI (GrantsInterface) and DOM manipulators (DOMConnector), through an event-driven system.
This method is fundamental to the library's operation, enabling dynamic responses to user choices. It can modify a single category's status or update all non-required categories simultaneously using a wildcard. Its execution triggers a cascade of events that ensures the user's preferences are immediately and consistently applied across the application.
Sources: src/modules/ConsentManager.ts:153-183, README.md:90-99
Core Logic and Execution Flow
The setGrant method resides within the ConsentManager class and is responsible for validating and applying consent changes. The process involves checking for required categories, updating the internal grants object, dispatching events, and persisting the state.
Sources: src/modules/ConsentManager.ts:153-183
Parameters
The method accepts two arguments to define the consent change.
| Parameter | Type | Description |
|---|---|---|
id | G | * | The unique identifier of the category to update, or '*' to update all non-required categories at once. |
status | boolean | The new consent status: true to grant consent, false to revoke it. |
Sources: src/modules/ConsentManager.ts:153-153
Execution Flow
The following diagram illustrates the step-by-step logic executed when setGrant is called.
This diagram shows the logical flow of the setGrant method, including its handling of wildcards and required categories.
Sources: src/modules/ConsentManager.ts:153-183, src/modules/ConsentManager.test.ts:70-79
Key Logic Points
- Wildcard Handling: If the
idis'*', the method iterates through all configured categories and recursively calls itself for each one, effectively applying thestatusto all non-required categories.
Sources: src/modules/ConsentManager.ts:155-160 - Category Validation: The method checks if the provided
idcorresponds to an existing category. If not, the operation is aborted.
Sources: src/modules/ConsentManager.ts:163-165, src/modules/ConsentManager.test.ts:95-102 - Required Category Check: It verifies if a category is marked as
required. Attempts to change the status of a required category are ignored to ensure essential functionalities are not disabled.
Sources: src/modules/ConsentManager.ts:168-173, src/modules/ConsentManager.test.ts:70-79 - State Update: For a valid, non-required category, the
grantsobject is updated with the new booleanstatus.
Sources: src/modules/ConsentManager.ts:175-175 - Customization Flag: The
isCustomizedproperty of theConsentManagerinstance is set totrue, indicating that the user has actively made a choice.
Sources: src/modules/ConsentManager.ts:181-181 - Cookie Persistence: The
writeCookiemethod is called to save the updatedgrantsobject and configurationversionto the browser's cookies.
Sources: src/modules/ConsentManager.ts:182-182, src/modules/ConsentManager.ts:143-151
Event Dispatching
A crucial function of setGrant is to announce consent changes to the rest of the application using an event system. This decouples the core consent logic from other modules that need to react to these changes, such as the GrantsInterface and DOMConnector.
Sources: src/modules/ConsentManager.ts:177-180
Dispatched Events
When a grant is successfully updated, setGrant dispatches two events in sequence.
| Event Name | Trigger Condition | Description |
|---|---|---|
update | Always on change | Fired whenever a category is either granted or revoked. |
grant | When status is true | Fired specifically when a category's consent is granted. |
revoke | When status is false | Fired specifically when a category's consent is revoked. |
Sources: src/modules/ConsentManager.ts:178-180, README.md:101-105
The dispatch method iterates through registered listeners for a given event and executes their callback functions, passing the category id as an argument.
Sources: src/modules/ConsentManager.ts:202-210
Integration with Other Modules
The setGrant method is the integration point for UI components and DOM controllers. They either call setGrant to initiate a change or listen for its events to react to a change.
GrantsInterface
The GrantsInterface module provides UI elements like a cookie banner and a preferences modal. User interactions with these elements directly call the setGrant method.
- Accept All: Clicking the "Accept All" button in the banner or modal calls
client.setGrant('*', true). - Reject/Only Required: Clicking the "Reject" or "Only required" button calls
client.setGrant('*', false). - Category Toggles: Changing a checkbox for an individual category in the preferences modal calls
client.setGrant(category.id, isChecked).
Sources: src/modules/GrantsInterface.ts:74-76, src/modules/GrantsInterface.ts:82-84, src/modules/GrantsInterface.ts:161-164
The following sequence diagram shows how a user interaction with the GrantsInterface banner leads to a call to setGrant.
This diagram illustrates the sequence of events when a user accepts all cookies via the UI.
Sources: src/modules/GrantsInterface.ts:74-76, src/modules/GrantsInterface.ts:100-104
DOMConnector
The DOMConnector module listens for the update event dispatched by setGrant. Upon receiving this event, it re-evaluates the DOM and modifies elements based on the new consent status.
In its constructor, DOMConnector registers a listener: client.on('update', this.updateDOM.bind(this)). When setGrant is called and dispatches the update event, the updateDOM method is triggered, which then applies or removes attributes from elements with data-consent-manager based on the latest grants.
Sources: src/modules/DOMConnector.ts:5-6
The following diagram shows how DOMConnector reacts to a consent change initiated by setGrant.
This diagram shows how DOMConnector listens for an update event and modifies the DOM accordingly.
Sources: src/modules/DOMConnector.ts:5-6, src/modules/DOMConnector.ts:28-46
Summary
The setGrant method is the engine of the consent-manager library. It provides a robust and centralized API for managing user consent. Through its clear execution logic, wildcard support, and event-driven architecture, it enables seamless integration with UI components like GrantsInterface and dynamic content modules like DOMConnector. By handling state changes, persistence, and notifications, setGrant ensures that user preferences are respected and consistently applied throughout the application lifecycle.
Sources: src/modules/ConsentManager.ts, src/index.ts