Blocks: Creating Reusable UI Components with Input Parameters and Local Variables

Blocks: Creating Reusable UI Components

Quick Answer: An OutSystems Block (formerly Web Block) is a reusable UI fragment — a self-contained screen chunk with its own widgets, Data Actions, local variables, input parameters, and Events. Unlike a Screen, a Block has no URL, cannot be navigated to directly, and is always embedded inside a Screen or another Block. Blocks are the primary mechanism for UI reuse in Reactive Web Apps, and the Associate Developer exam tests input parameters, local variables, Data Actions, and when to build one versus duplicating markup.

What Is a Block?

A Block encapsulates a fragment of a screen. You create it in Service Studio under the UI layer, and it appears in the Toolbox once defined. When you drag a Block onto a Screen, Service Studio creates an instance — the Block's widgets, logic, and Data Actions run within the host Screen's context, but the Block maintains its own scope for local variables and events.

Key structural characteristics distinguish a Block from a Screen:

Blocks do not have the full Screen lifecycle (OnInitialize, OnReady, OnRender). Instead, a Block reacts to its input parameters through the OnParametersChanged event, which fires when the parent passes new values — for example, when the parent receives a new URL parameter and passes it down to the Block.

Block Input Parameters vs Local Variables

This distinction is one of the most tested Block concepts on the exam. Input parameters and local variables serve fundamentally different roles:

Input parameters make a Block reusable: the same CustomerCard Block can render customer 42 on one Screen and 107 on another because each parent passes a different CustomerId. Setting Is Mandatory = Yes forces TrueChange to flag any placement missing that parameter.

Local variables are the Block's private state. The parent cannot read or write them. If the parent needs to know a Block's internal state — for example, that a Save button was clicked — the Block must raise an Event. Local variables alone cannot communicate outward.

Block Data Actions and the Refresh Cycle

A Block can contain its own Data Actions — server calls that fetch data scoped to the Block's needs. When you place a Block on a Screen, its Data Actions execute on first render, just like Screen-level Data Actions. The Data Action can use input parameters in its fetch logic: a ProductId input parameter filters an Aggregate so the Block loads only the relevant product.

OnAfterFetch is a Client Action that fires after the Data Action's server call returns and data reaches the client. Developers use it to post-process records — computing derived values, selecting the first item, or setting a local variable.

To force a Block's Data Action to re-run after input parameters change, call RefreshData inside the Block's OnParametersChanged handler. The full refresh sequence is:

1. Parent changes the value bound to the Block's input parameter (e.g., user selects a different customer from a list)
2. Block's OnParametersChanged event fires automatically
3. Inside OnParametersChanged, the Block calls RefreshData on its Data Action
4. Data Action re-executes the server call with the new parameter value
5. OnAfterFetch processes the fresh results on the client

This five-step cycle is the standard pattern for keeping a Block's data in sync with its input parameters.

When to Build a Block vs Duplicate UI

Build a Block when:

• The same UI fragment appears on two or more Screens (e.g., a customer summary card used on a list page and a detail page)
• The fragment needs self-contained data fetching scoped to a parameter (e.g., a chart that loads its own data based on a WidgetId)
• The fragment needs encapsulated event communication back to the parent (e.g., a Save button that notifies the parent to refresh)
• The fragment is part of a design system consumed across multiple modules

Duplicate the UI instead when:

• The fragment appears on only one Screen — a Block adds overhead with no reuse benefit
• The fragments look similar but diverge significantly in behavior or layout — forcing them into one Block requires so many conditional branches it becomes harder to maintain than two copies
• The fragment is screen-specific and will never be reused

The practical rule: extract a Block at the second reuse, not the first.

Publishing and Consuming Blocks Across Modules

Blocks can be shared across modules. In the producer module, set the Block's Public property to Yes. In the consumer module, add a dependency on the producer module, then drag the Block onto any Screen. The consumer sees the Block's input parameters and must handle its Events, but cannot modify the Block's internal widgets, local variables, or logic — it is a black box.

This pattern enables design systems: a shared UI module publishes Blocks (header, footer, card), and feature modules consume them for consistent UI without duplicating markup. When the producer 1-Click Publishes, consumers pick up changes after re-publishing.