import { registerEventListener } from '@uhg-abyss/parcels/tools/registerEventListener';

Overview

The registerEventListener tool is used to register event listeners for custom events dispatched to the window, enabling communication between Parcels and the host site or between multiple Parcels. It is useful for listening to events dispatched by other components and is meant to be used in conjunction with the dispatchEvent tool.

Important

registerEventListener is meant for projects that are not using React. You will need to use lifecycle callbacks to prevent memory leaks. This differs from the useRegisterEventListener hook, which handles lifecycle management automatically.

React-based projects should use useRegisterEventListener.

This tool is bidirectional, meaning that it can be used to register events in both web and parcel components.

Properties

registerEventListener(
  eventName: string,
  handler: (event) => void,
):

Usage

registerEventListener takes in two parameters:

1. eventName: a string representing the name of the custom event to listen for.
2. handler: a callback function that is executed when the event is dispatched.

() => {
  const [text, setText] = useState('Hello');

  // For teams not using React you will need to look into different lifecycle hooks to prevent memory leaks

  // Memoize the event handler using useCallback to ensure a stable reference
  const handleWebSubmit = useCallback((event) => {
    setText(event.detail.message);
  }, []); // No dependencies, setText won't change

  useEffect(() => {
    // Register event listener using the memoized handler function
    const unregister = registerEventListener('webSubmit', handleWebSubmit);

    // Specify how to clean up after this effect:
    return () => {
      unregister(); // Unregister event listener when the component unmounts or dependencies change
    };
  }, [handleWebSubmit]); // Dependencies array includes the memoized handler

  return <div>{text}</div>;
};

Example

// Example web file
import React from 'react';
import { Button } from '@uhg-abyss/web/ui/Button';
import { dispatchEvent } from '@uhg-abyss/parcels/tools/dispatchEvent';

export const HelloAbyss = () => {
  // Add a dispatch event to the web component
  const onSubmit = () => {
    // When the button is clicked, the event will be dispatched
    dispatchEvent('webSubmit', { message: 'Form submitted!' });
  };
  return (
    <div>
      <abyss-parcel import="parcel-app@test" />
      <Button onClick={onSubmit}>Hello</Button>
    </div>
  );
};

// Example parcel file
import React, { useCallback, useEffect, useState } from 'react';
import { registerEventListener } from '@uhg-abyss/parcels/tools/registerEventListener';

export const ParcelApp = () => {
  const [text, setText] = useState('Hello');

  // Memoize the event handler using useCallback to ensure a stable reference
  const handleWebSubmit = useCallback((event) => {
    setText(event.detail.message);
  }, []); // No dependencies, setText won't change

  useEffect(() => {
    // Register event listener using the memoized handler function
    const unregister = registerEventListener('webSubmit', handleWebSubmit);

    // Specify how to clean up after this effect:
    return () => {
      unregister(); // Unregister event listener when the component unmounts or dependencies change
    };
  }, [handleWebSubmit]); // Dependencies array includes the memoized handler
  return <div>{text}</div>;
};