- Control Flow Brick Output
- When to use Control Flow Bricks
- Control Flow Brick Details
- For-Each Loop
- Raising Exceptions/Errors
- Frequently Asked Questions
- Why aren’t the outputs of bricks nested within a Control Flow Brick available outside the Control Flow brick?
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.
In the Extension Overview, the Control Flow brick appears as a brick with a top/bottom section, and one or more branches of bricks:
Control Flow Brick Output
There are two behaviors to know about how output works in Control Flow bricks:
- The Control Flow brick outputs the value of the final brick it ran that has an Output Key
- 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:
When to use Control Flow Bricks
The following table describes scenarios where you might use each type of control flow brick:
Control Flow Brick
You need to run multiple bricks if a condition is met
You need to run one block(s) if a condition is met, and a different block(s) if the condition is not met
You are calling an API that sometimes fails
You want to wait for a condition to be met. For example: an API result to change
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
You want to ignore an error code when calling an an API
Leave the catch branch blank
You want to perform an action for each item in a list of items returned from an API
By default an
You want to perform an action for each element currently on the page that matches a selector
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
- The error is made available in the
catchbranch. By default, the error is made available to the catch branch as
@error. The error message/description is available as
- An error that occurs in the
trybranch 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
- By default, the current element is made available as
There are two bricks for exceptional control flow:
- Raise a Business Error: logged as an error in error telemetry
- Cancel Current Action: not reported as an error. For example, the user cancelled a form
When a Raise Business Error or Cancel Current Action brick is run, the extension 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 extension 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?
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