Code Blocks

Code Blocks in the Expression Engine behave as functions (i.e. can define a return value). These blocks consist of code lines and can use internal variables. Access to internal variables is fast and a single variable can contain any data type that a standard expression value can hold (simple types, arrays, etc.). Internal variables do not need type definitions. Every internal variable starts with an @ character and can be a combination of alphanumeric characters. The default value for all internal variables is an "Empty" value. Internal variables defined in the main code block can be used by inner code blocks or code lines sections.

Main code block

Main code blocks have two basic sections -- variable declarations (optional), and code lines section. Each data block internally defines a return variable with a special, well-known name - @@.

When the declare section is not specified, then the only available internal variable is the return value @@. The variable declaration section can define any number of internal variables. Each variable can be optionally initialized. The variable declaration line ends with a semicolon character.

As was mentioned earlier, multiple code blocks can be used side-by-side inside an expression:

Is equivalent to

These examples are used to demonstrate code blocks behavior as functions and how to specify a return value inside a code block. In this example, both code blocks are independent, thus cannot share their internal variables. To be able to share variables between separate code blocks, one upper code block is necessary:

Code Lines

Each code line starts with a keyword and ends with a semicolon character.

SET Statement

This is used to set internal variables. The following is the SET syntax:

Where variable_name specifies the internal variable declared in the declare section and the value can be any standard expression [combination of functions, operators and variables (internal or external)].

Examples:

EXIT Statement

This command allows for a code block to exit and terminate earlier without completing other operations. It can be used as a simple EXIT command, where it makes sense in combination with an IF statement or conditional exit with WHEN part specified:

or

The Exit command is not propagated to upper code blocks and will only affect the current code block.

Examples:

FOREACH Loop

Simple loop designed to iterate through arrays. The syntax is as follows:

where counter_variable is an internal variable, which is declared by FOREACH statement -- i.e. doesn't need to be explicitly declared beforehand. This variable is known inside the loop body only and contains a current array element. The array_value is any expression (functions, operators, etc.) that can return an array. In case it returns a simple value (non-array value), it is converted by the expression conversion mechanism to a single element array.

Looping can be stopped earlier (if needed) by an EXIT statement.

Examples:

Or without using an explicitly declared variable:

With Exit statement:

FOR Loop

The FOR loop is always looping between specified numbers and optionally allows for specifying direction and step values. Loop values (from, to, step) are read before looping starts, thus any changes to these parameters via internal variables won't take any effect to actual loop. Looping can be stopped earlier (if needed) by EXIT statement.

The syntax is as follows:

Where counter_variable is an internal variable, which is declared by FOR statement -- i.e. doesn't need to be explicitly declared. This variable is known inside the loop body only and contains current counter value. The lowest and highest numbers determine the FOR-loop range. To start looping, the lowest number must contain a lower value than the highest number. When REVERSE is specified, then it starts looping from the highest number and ends in the lowest value. STEP is followed by a numeric value that specifies the increment value used in FOR loop. The default value is 1.

Examples (without code block):

FOR loop can use internal/external variables in place of lowest/highest and step numbers. See full examples below:

IF AND IFQ Statements

IF statements can be used directly in code blocks. Their behavior is very similar to IF used in standard expression text. The only difference is that THEN and ELSE values are not expressions, but either a code line or another code block. The ELSE section is optional.

The syntax is as follows:

Examples:

CASE-WHEN-THEN Statements

CASE statements can be used directly in code blocks and their behavior is very similar to CASE statements used in standard expression text. The only difference is that THEN and ELSE values are not expressions, but either code lines or another code block. The ELSE section is optional.