The PubSubEvents module implements a client-side Publish/Subscribe (Pub/Sub) Event Bus designed to promote clean architecture by enabling decoupled communication between UI Blocks and Screens.

It solves common challenges like event bubbling and reliance on OnParametersChanged for cross-component UI synchronization.

1. Installation

1. Open your OutSystems environment (Service Studio).

2. Search for and install the PubSubEvents component from the Forge.

3. Add a reference to the PubSubEvents module in any application module that requires event messaging.

2. General Usage Guide

The component utilizes two core actions: SubscribeToEvent (the Listener) and PublishEvent (the Sender).

Step 1: Subscribing to an Event (The Listener)

This is done by the component that needs to receive a message.

1. Define the Handler: In the subscribing Block or Screen, create a Client Action that will handle the incoming event. This action must accept one input parameter whose Data Type matches the expected Payload (e.g., UserId, Boolean, or a specific Structure).

2. Register the Listener: In the subscribing Block's OnReady client event:

   • Call the SubscribeToEvent action.

   • Set the EventId to a unique string (e.g., "FilterApplied").

   • Set the CallbackAction to the Client Action you created in step 1.

Step 2: Publishing an Event (The Sender)

This is done by the component that needs to send a message.

1. Determine the Channel: Use the same unique EventId string used by the subscriber (e.g., "FilterApplied").

2. Dispatch the Message: Call the PublishEvent action, providing the EventId and the relevant data in the Payload input.

3. Best Practices & Security Guidelines

Security Warning: Never Trust the Client

• The data transmitted via the Pub/Sub bus is client-side and can be manipulated by a malicious user.

• The Rule: If an event triggers a Server Action (e.g., saving data, fetching records), the Server Action must perform a full authentication and authorization check on the server side. Do not rely on the Payload data as proof of legitimacy or access rights.

Usage Tips

• Consistency (Recommended): For medium to large applications, create one or more static entities in your application's Core/Shared Services module to manage all your event IDs (e.g., EventIdReference). This prevents typos, allows for code auto-completion, and centralizes your communication contracts.

• Naming: Use PascalCase for your EventId names (e.g., FormValidated, DataRefreshRequested).

• Decoupling: Avoid calling PublishEvent and SubscribeToEvent in the same Block/Screen unless absolutely necessary. The power of this component is coordinating separate UI elements.

• Lifecycle: Always register subscribers in OnInitialize or OnReady to ensure the listener is active before any PublishEvent calls are made.