Blocks: Creating Reusable UI Components with Input Parameters and Local Variables
Key Takeaways
An OutSystems Block (formerly Web Block) is a reusable UI fragment embedded in Screens or other Blocks; it has its own Data Actions, Client/Server Actions, local variables, input parameters, and Events, but no URL and cannot be navigated to directly.
Block input parameters receive values from the parent Screen when the Block is placed and are read-only inside the Block; Block local variables are internal working state that the parent cannot see or set, making Blocks configurable without exposing internal state.
A Block Data Action fetches server data scoped to the Block's lifecycle; it runs on first render and can be refreshed via RefreshData, and its OnAfterFetch Client Action fires after the data returns to the client for post-processing.
Build a Block when the same UI fragment is reused on two or more Screens or when self-contained data fetching and event communication are needed; duplicate the UI when the fragment appears once or diverges significantly across contexts.
Blocks can be public (Public property = Yes) and consumed by other modules; the consumer references the producer module, drops the Block onto any Screen, and must supply input parameters and handle Events, but cannot modify the Block's internal widgets or 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:
| Property | Block | Screen |
|---|---|---|
| Has a URL | No | Yes |
| Navigable directly | No | Yes |
| Can raise Events | Yes | No |
| Embedded in other elements | Yes | No (standalone) |
| Full lifecycle (OnInitialize, OnReady, OnRender) | No | Yes |
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:
| Aspect | Input Parameter | Local Variable |
|---|---|---|
| Who sets the value | Parent Screen when placing the Block | Block's own logic (Assign, default) |
| Visibility to parent | Parent must supply if Mandatory | Parent cannot see or set it |
| Mutability inside Block | Read-only | Read and write |
| Example | CustomerId, ReadOnly flag | IsExpanded, SelectedTabIndex |
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:
- Parent changes the value bound to the Block's input parameter (e.g., user selects a different customer from a list)
- Block's OnParametersChanged event fires automatically
- Inside OnParametersChanged, the Block calls RefreshData on its Data Action
- Data Action re-executes the server call with the new parameter value
- 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.
In OutSystems Reactive Web Apps, what is a Block (formerly Web Block)?
A database transaction unit that ensures ACID compliance across server calls
A reusable UI component — a screen fragment with its own widgets, Data Actions, local variables, input parameters, and Events that is embedded inside Screens
A Forge component that blocks spam submissions in user-generated content forms
A code section that is blocked from executing during server-side load balancing
How do Block input parameters differ from Block local variables?
Input parameters are stored in the database; local variables are in-memory only
Input parameters and local variables are identical — both can be modified by the parent Screen
Input parameters are only available in Traditional Web Apps; local variables are only in Reactive Web Apps
Input parameters receive values from the parent Screen when the Block is placed and are read-only inside the Block; local variables are the Block's internal state and cannot be seen or set by the parent
A Block displays a product chart based on a ProductId input parameter. When the parent passes a new ProductId, what is the correct sequence to refresh the Block's data?
The Data Action automatically re-runs whenever any input parameter changes — no explicit action is needed
The Block's OnParametersChanged event fires, and inside it you call RefreshData on the Data Action, which re-fetches with the new ProductId, then OnAfterFetch processes the results on the client
The parent Screen must call a Server Action to manually re-query the database and pass the full result set into the Block via a new input parameter
The Block must be destroyed and re-placed on the Screen each time the ProductId changes
You have a customer summary card that appears on the customer list Screen and the customer detail Screen, each showing a different customer. When should you build a Block versus duplicating the UI?
Build a Block because the same UI fragment is reused on two or more Screens and can be parameterized with a CustomerId input parameter for each context
Always duplicate the UI — Blocks add unnecessary overhead and should be avoided in Reactive Web Apps
Build a Block only if the card appears on five or more Screens — the reuse threshold for Blocks is five
Duplicate the UI because Blocks cannot accept input parameters to differentiate between customers
Sections you finish are checked off in the contents.