Observe Content

The LmnObserveContentDirective is an Angular attribute directive that utilizes the browser's MutationObserver API to monitor and report changes to the DOM content of its host HTML element. This includes changes to the element's direct children, its subtree, character data, and attributes. It provides a straightforward way to react to DOM mutations without manually managing MutationObserver instances.

Technical Overview

The lmnObserveContent directive, when applied to an HTML element, creates a MutationObserver instance (if not in a server-side rendering context). This observer is then configured with options (defaulting to observe character data, child list, and subtree changes) and attached to the host element. When any of the configured mutations occur within the host element's DOM, the directive emits an event.

The directive is responsible for the lifecycle of the MutationObserver, including its creation, observation according to the provided configuration, and disconnection when the directive is destroyed or explicitly disabled.

Key Features

• DOM Content Monitoring: Uses MutationObserver to detect a wide range of changes within the host element's content, such as added/removed nodes, text changes, and attribute modifications.
• Event Emission: Emits an LmnObserverContentEvent ({ element: HTMLElement, mutations: MutationRecord[] }) when a DOM mutation is detected.
• Configurable Observer: Allows specifying MutationObserverInit options via an input to customize what types of mutations are observed (e.g., attributes, characterData, childList, subtree).
• Disabled State: Observation can be dynamically enabled or disabled using an input.
• Lifecycle Management: Automatically creates the observer and disconnects it on destroy or when disabled.
• SSR Safe: Includes checks for server-side rendering to prevent errors when MutationObserver is unavailable.
• Initial Emission: Emits an event with an empty mutations array after the next render cycle if not disabled, allowing for initial setup or checks based on the content.

When to Use

Use the LmnObserveContentDirective when:

• You need to react to dynamic changes in an element's content (e.g., children being added or removed, text content updates).
• You want to trigger actions when specific DOM mutations occur within a component or element.
• You need a declarative way to interface with the MutationObserver API.
• You are building components that need to adapt to or validate their projected content.

Implementation

Apply the [lmnObserveContent] directive to the HTML element whose content you wish to monitor.

Selector: [lmnObserveContent]

Inputs:

• lmnObserveContentDisabled (alias disabled): Optional (boolean, default: false). If true, the MutationObserver will be disconnected, and no mutation events will be emitted.
• lmnObserveContentMutationObserverConfig (alias mutationObserverConfig): Optional (MutationObserverInit, default: { characterData: true, childList: true, subtree: true }). Allows providing a custom configuration object for the MutationObserver. Refer to MDN documentation for MutationObserverInit for all available options.

Outputs:

• lmnObserveContent (alias event): Emits an LmnObserverContentEvent object when a configured DOM mutation is detected within the host element. The event object contains:
  • element: HTMLElement: The host element being observed.
  • mutations: MutationRecord[]: An array of MutationRecord objects detailing the changes that occurred. This array will be empty for the initial emission after render.