events.md

Event Handling

https://github.com/RoamJS/roamjs-components/blob/main/src/events

Utilities for setting up and managing event listeners in the Roam Research application are centralized in https://github.com/RoamJS/roamjs-components/blob/main/src/events. The primary function provided is watchOnce, which allows for one-time event listening.

• watchOnce is designed to monitor changes in a specific Roam Research block and execute a callback function when a change is detected.
• It takes three parameters: pullPattern (the pattern to watch for), entityId (the block ID to watch), and callback (the function to execute upon detection).

The function operates as follows:

• Sets up a watcher using window.roamAlphaAPI.data.addPullWatch(), passing the pullPattern, entityId, and a custom watcher function.
• The custom watcher function invokes the callback with before and after PullBlock objects.
• If the callback returns true, the watcher is removed using window.roamAlphaAPI.data.removePullWatch().

This utility is useful for scenarios where an action needs to be performed once upon a block's update, such as updating a visualization or triggering a notification.