📖
PixieBrix Documentation
🆒

Control Flow Brick Reference

Introduction

Release 1.7.0 (June 2022) introduced support for Control Flow bricks that “control” the order and sequence in which the bricks nested inside them run.

There are 4 primary control flow bricks: If-Else, For-Each, Try-Except, and Retry:

  • If-Else: if a condition is met, run one the “if” branch of bricks, otherwise run the “else” branch of bricks
  • Try-Except: run a “try” branch of bricks, recovering by running the “catch” branch of bricks if there’s an error or the user cancelled the run
  • Retry: run a body of bricks, and re-run the body if there’s an error
  • For-Each: for each element in a list/array, run a body of bricks, providing a different element to the body for each run

The Document Builder also uses control flow for the Button element handler, and the Brick element. The information on this page also applies to bricks you add to those elements.

📖
When a Control Flow brick has multiple sub-sequences of bricks, we will call them “branches”. When a Control Flow brick contains a single sequence of bricks, we will call it the “body”.

In the Mod Overview, the Control Flow brick appears as a brick with a top/bottom section and one or more branches of bricks:

The If-Else brick. If the condition is true, PixieBrix will show confetti. If the condition is false, PixieBrix will show an alert
The If-Else brick. If the condition is true, PixieBrix will show confetti. If the condition is false, PixieBrix will show an alert

Control Flow Brick Output

There are two behaviors to know about how output works in Control Flow bricks:

  1. The Control Flow brick outputs the value of the final brick it ran that has an Output Key
  2. The Output/Output Key of a brick within a Control Flow brick is only available to the subsequent bricks within the same branch/body. It is not available outside of the Control Flow brick or inside the other branches

If you need the Control Flow brick to output a brick other than the final brick, currently the best way to do so is using the jq - JSON Processor brick.

Provide the following inputs:

Input
Value
filter
.
data
@key of the data you want the Control Flow brick to output

Using the jq - JSON processor brick to select a particular brick output for the
Using the jq - JSON processor brick to select a particular brick output for the

When to use Control Flow Bricks

The following table describes scenarios where you might use each type of control flow brick:

Scenario
Control Flow Brick
Discussion
You need to run multiple bricks if a condition is met
If-Else
You need to run one block(s) if a condition is met, and a different block(s) if the condition is not met
If-Else
You are calling an API that sometimes fails
Retry
You want to wait for a condition to be met. For example: an API result to change
Retry
In the Retry body, add a “Cancel Current Action” that runs if the condition has not been met yet (See Exceptions/Errors below)
You want to wait for an element to appear on the page
N/A - use the Wait for a DOM element brick
Trick question! The Wait for a DOM element brick has better performance because it can use native browser APIs to detect new elements
You want to show a custom error message/instructions to the user if a brick fails
Try-Except
You want to ignore an error code when calling an an API
Try-Except
Leave the catch branch blank
You want to perform an action for each item in a list of items returned from an API
For-Each
By default an @element key is made available to the body. You can customize the name of the key provided to the body
You want to perform an action for each element currently on the page that matches a selector
For-Each Element
Current the Page Editor does not support selecting multiple elements. You must manually tweak the automatically generated selector to match multiple elements

Control Flow Brick Details

Try-Except

  • The error is made available in the catch branch. By default, the error is made available to the catch branch as @error. The error message/description is available as @error.message
  • An error that occurs in the try branch will not be reported to the PixieBrix error telemetry service. To record the error, add a Send Telemetry brick or Put data in a PixieBrix database brick to the catch branch

For-Each Loop

  • By default, the current element is made available as @element

Raising Exceptions/Errors

There are two bricks for exceptional control flow:

When a Raise Business Error or Cancel Current Action brick is run, the mod will stop running and the bricks following the brick will not be run.

If an error is raised in a Control Flow brick, the Control Flow brick will also error. However, when using the Try-Except and Retry bricks, the try-branch and retry body will handle the exception, and the mod will continue running.

Frequently Asked Questions

Why aren’t the outputs of bricks nested within a Control Flow Brick available outside the Control Flow brick?

PixieBrix Control Flow bricks are implemented similar to closures in popular programming languages like Javascript.

By “freezing” the environment passed into a branch/body of a Control Flow brick and preventing it from modifying the available Output Keys outside of the brick, the behavior of bricks are more predictable (to PixieBrix’s debugger and humans!). Predictability allows use cases like button handlers and rendering sub-panel elements in parallel

Twitter