Skip to Content (Press Enter)
Community › Forge › Assets list › PubSubEvents
pubsubevents
Reactive icon

PubSubEvents

version 1.0.1 (Compatible with OutSystems 11)
Uploaded
 on 27 Aug
 by 
0.0
 (0 ratings)
pubsubevents

PubSubEvents

Documentation
1.0.1

Installation

  1. Install from Forge

    • Add the PubSubEvents component to your OutSystems environment.

    • Publish the module to make it available in your applications.

  2. Add Dependencies

    • Reference the PubSubEvents module in any app where you want to use the event bus.

    • The EventSubscriber block and PublishEvent client action will be available in your toolbox.


Configuration

No setup required—just plug and play.

  • EventSubscriber Block

    • Drag the block into any screen or UI component.

    • Set the EventId input to the name of the event channel you want to listen to.

    • The block automatically subscribes on initialization and unsubscribes on destroy.

    • When an event is received, it triggers the built-in NotifySubscriber event, which bubbles up to the parent block or screen.

  • PublishEvent Client Action

    • Call this action from any block or screen to broadcast an event.

    • Provide the same EventId used by subscribers and an optional Payload.


Usage Instructions

Subscribing to Events

Use the EventSubscriber block like this:

plaintext

EventId: "UserProfileUpdated"

Then, in the parent block or screen, handle the NotifySubscriber event to respond to the published message.

📤 Publishing Events

Use the PublishEvent client action to send messages:

plaintext

EventId: "UserProfileUpdated"
Payload: { UserId: 123 }

All blocks with a matching EventId will receive the event and trigger their NotifySubscriber handlers.


🧠 Best Practices

  • Use PascalCase for EventId names to keep things consistent—Consider Static entitie(s) for managing event Ids.

  • Keep payloads minimal—prefer identifiers over full records.

  • Avoid transmitting sensitive data through the event bus.

  • Always validate user roles and permissions server-side before executing critical logic.


1.0.0

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.