Code Blocks Reference
Code blocks run multiple statments of code. They are used in {run}, {button} and also block functions.
Code blocks build on the {=} (Formula Command) but instead of evaluating a single expression, they run one or more statements consisting of multiple expressions. This allows you to implement complex logic in a more maintainable manner than you can with formulas.
For example, you could create a task list snippet that allows you to add and remove tasks:
Task List:{run: tasks = ["Take out the garbage", "Wash the car"]} {repeat: for task in tasks} {=task} {button: var index = location(tasks, task) tasks = merge(slice(tasks, 1, index - 1), slice(tasks, index + 1)) ; label=🗑️}{endrepeat}
New Task: {formtext: name=task; default=} {button: if task = "" notify("Task cannot be blank") return endif tasks = merge(tasks, [task]) task = "" ; label=Add Task}
The following outlines the supported statements.
Assignment
The assignment statement allows you to assign values in a block. For example:
{run: x = 2 y = 3 z = x * y }
x: {=x} y: {=y} z: {=z}
By default, assignments are applied to the global scope of the snippet. If you want to make an assignment within the context of the block that is not applied to the global scope, you can preface the initial definition of the variable with var.
For example:
{run: x = 2 var y = 3 z = x * y }
x: {=x} y: {=y} (y is not defined here as it was defined only in the local scope of the run command) z: {=z}
If Statement
The if statement allows you to conditionally execute logic. It may optionally contain one more elseif statments and may optionally include a single else statement.
{run: x = 2 if x < 0 description = "x is negative" elseif x > 100 description = "x is a big number" else description = "x is a small number" endif }
x: {=x} description: {=description}
For Loop Statement
For loops allow you to iterate over a list of values. The loop body is executed once for each item in the list.
{run: sum = 0 for value in [121, 54, 32, 123, 44] sum = sum + value endfor }
The sum of items is: {=sum}
Try and CatchError Statements
Try statements allow you to evaluate code which may fail with an error. If an error occurs within the try...endtry bounds the code will continue to be processed after the endtry.
{run: status = "Starting action" completed = no try error("An error for testing") status = "Action succeeded" endtry completed = yes }
The status is not set as an error occurred. Evaluation continued after the endtry which is why completed is set.
Completed: {=completed} Status: {=status}
Try blocks may optionally include a CatchError block. If an error occurs in the Try, the CatchError block will be executed. If no error occurs in the Try, the CatchError block will not be executed.
{run: try error("An error for testing") status = "Action succeeded" catcherror status = "Action failed" endtry }
Status: {=status}
Return Statements
A Return statement will end execution of a code block at the point of the return.
{formtext: name=text} {run: text_upper = "[Nothing uppercased yet]"} {button: if text = "" # if there is no text we won't try to process it return endif
text_upper = upper(text) ; label=Uppercase it } (will only uppercase if the formtext is not blank)
Uppercased: {=text_upper}
Functions
You can define functions that contain blocks. The body of block functions should start with a block statement and end with an endblock statment.
The return statement within block functions will return values from the function.
Function to calculate a Fibonacci number {fibonacci=(i) -> block if round(i) <> i error("fibonnaci requires an integer") endif
if i < 0 error("The number must be greater than or equal to 0") endif
if i = 0 return 0 endif
if i = 1 return 1 endif
var x = 0 var y = 1 var sum = 0
for num in seq(2, i) sum = x + y x = y y = sum endfor
return sum endblock}
Fibonnaci(0) = {=fibonacci(0)} Fibonnaci(1) = {=fibonacci(1)} Fibonnaci(2) = {=fibonacci(2)} Fibonnaci(3) = {=fibonacci(3)} ... Fibonnaci(7) = {=fibonacci(7)} Fibonnaci(8) = {=fibonacci(8)} Fibonnaci(9) = {=fibonacci(9)}
Error cases:
Fibonnaci(-10) = {=fibonacci(-10)} Fibonnaci(1.5) = {=fibonacci(1.5)}
Comments
You may use comments in block to add notes and other pieces of information. Comments are started with a #. Everything after a # on a line is treated as a comment and is not evaluted.
{run:
# define the input values x = 3 y = 2
# check they are both greater than 0 if x <= 0 or y <=0 error("x and y must be greater than 0") # an error to show endif
# multiply them output = x * y }
Output: {=output}
Commands
You can use many types of commands within your code blocks. This can be useful include things like the {clipboard} or {time}. Commands that require user interactivity (e.g. {formtext}) or are interleaved with snippet contents (e.g. {note}), cannot be included in code blocks.
{run: clicks = []} {button: # use the {time} command to get the click time clicks = merge(clicks, [{time: HH:mm:ss}]); label=Click me }
Button presses occurred at at the following times: {repeat: for click in clicks} {=click} {endrepeat}
Connected Commands
You can include connected commands in blocks. At the top level of snippets, the following connected commands are evaluated when the snippet is previewed:
The following commands are only evaluated when a snippet is inserted:
When used in blocks, all these commands are run at the time they are encountered in the block. That means you can, for instance, add rows to a Data Blaze space from a form window without inserting the snippet.
Additionally, they return the result of the command as a list. For example, you could run:
row = {dbinsert: ...}
After this, row will be a named list where the key "id" is the id of the newly created row.
Load data from (simulated) API.
{run: temperature="Unknown"}
{button: data = fromJSON({urlload: https://blaze.today/api/temperature})
temperature = data.temperature; label=Click me to get the temperature }
The temperature is currently {=temperature}°
Functions
Code blocks running within {button} or {run} commands, have access to an additional function notify. notify will show a message as a toast to the user.