Widgets/Storage

Global Variable Widget

Global Variable Widget

A "Storage" type widget. Global Variable Widget allows widgets to set and read values from anywhere in the recipe. Global variables can be accessed from any widget in the recipe, organized in groups, and support various control types for different data types.

Key features:

  • Sharing configuration values across multiple workflows
  • Creating user-facing controls that can be modified at runtime
  • Storing values that need to persist across different parts of your recipe
  • Organizing related variables into groups

 

Inputs

  • read (DataType: Anything) Triggers the widget to output the current value of the global variable. If the variable exists and has a value, it will be transmitted through the "value" output port.

  • setValue (DataType: Configurable) Sets the global variable to the provided value. The data type must match the variable's configured control type. When triggered, the value is immediately stored and all widgets subscribed to this variable are notified. If the widget is in reactive mode, it will also forward the value to connected child widgets.


Outputs

  • value (DataType: Configurable) Transmits the current value of the global variable. The data type matches the variable's configured control type and the last value that was set. The output type is dynamically determined based on the variable's configuration.

Custom Settings

  • Variable Name The unique name for the global variable within your recipe. Variable names cannot contain dots (.) or hyphens (-). Use underscores (_) or spaces to separate words if needed. When you enter a variable name, a dropdown appears to help you select from existing global variable names.

  • Auto-emit on variable change Controls whether the widget automatically forwards values to connected child widgets when the variable changes.

    • Enabled: The widget automatically forwards the variable's value to connected child widgets in two scenarios:

      • When the "setValue" port is triggered, the widget sets the global variable value (notifying all subscribed widgets) and immediately forwards it through the "value" output port to connected child widgets.
      • When the variable is changed from another source (such as the Global Variables Panel or another widget), the widget automatically detects the change and forwards the new value to connected child widgets through the "value" output port.

    • Disabled: The widget sets or reads the global variable value but does not automatically forward it to connected child widgets. When "setValue" is triggered, the value is stored and all other widgets subscribed to the variable are notified, but the value is not automatically sent to this widget's connected child widgets. To read and forward the value, you must explicitly trigger the "read" input port.




Control Types

Global variables support different control types that determine how they appear in the UI and what data types they accept:

  • anything - Default type with no specific UI control. Can hold any value type.
  • number - Numeric input with optional min/max/step constraints. Accepts Number data type.
  • slider - Visual slider control with min/max/step settings. Accepts Number data type.
  • text - Single-line text input with optional placeholder. Accepts String data type.
  • multilineText - Multi-line text input with optional placeholder. Accepts String data type.
  • dropdown - Dropdown menu with predefined options. Accepts String data type.
  • multiSelect - Multi-select dropdown with predefined options. Accepts Array data type.
  • checkbox - Boolean checkbox control. Accepts Boolean or Number data type.
  • image - Image upload control. Accepts ImageData data type.
  • binaryFile - Binary file upload control. Accepts BinaryFile data type.
  • button - Button control that can trigger actions when clicked. Accepts Boolean data type.
  • group - A container for organizing variables. Created in the Global Variables Panel to structure related items, including nested levels. Other variables can be assigned to groups via Settings → Group or drag-and-drop.

 

Accessing Global Variables

When a Global Variable belongs to a group, its internal reference name becomes 'groupName.variableName'. Widgets that support variable access (such as Template String, Expression Eval, or Switch) must reference variables differently depending on whether they are grouped or standalone:

Grouped variables must use bracket notation with the full path:

{{$vars["groupName.variableName"]}}

Standalone variables (not in a group) can use dot notation:

{{$vars.variableName}}

Grouped variables use their full path as the storage key, while standalone variables use only their name.

 

📌 Important Notes

  • Variable Behavior: When the "setValue" port is triggered, the value is immediately stored, triggering a notification to all widgets subscribed to this variable. If the widget is reactive, it will also dispatch a notification to the next widget. This means that all other subscribers will always receive the latest value BEFORE the children widgets receive the event.

  • Type Validation: The widget validates that the data type of the incoming value matches the variable's configured control type. If there's a mismatch, an error will be thrown.

 

Examples

Example 1: Image Variable with Non-Reactive Mode (Manual Processing)

This example uses a Global Variable of type "image" with non-reactive mode. A Button Widget triggers the "read" port to process the stored image.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. A Global Variable widget is configured with:
    • Variable Name: "source_image"
    • Control Type: "image" (accepts ImageData data type)
    • Auto-emit on variable change: Disabled (non-reactive mode)
  2. A Button Widget triggers the "read" port on the Global Variable Widget
  3. When the "read" port is triggered, the Global Variable Widget outputs its current value
  4. The image flows to an Image Filter Widget that applies an invert filter
  5. The processed image is displayed in the Display Widget

 

Example 2: Number Variable with Reactive Mode (Automatic Calculation)

This example uses a Global Variable of type "number" with reactive mode. A Slider Widget sets the value, which is automatically forwarded to connected widgets for calculation.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Global Variable widget is configured with:
    • Variable Name: "multiply"
    • Control Type: "slider" (accepts Number data type)
    • Auto-emit on variable change: Enabled (reactive mode)
  2. A Slider Widget provides a numeric value (1-10) that is sent to the Global Variable Widget through the "setValue" port
  3. Reactive mode forwards the updated value automatically to the Expression Eval Widget, which multiplies it by 2
  4. The result is displayed in the Display Widget
  • Generate Event with Current Value You can disconnect the Slider Widget and control the variable directly from the Global Variables Panel. Change the value of "multiply" in the panel and click the "Generate event with current value" button (▶ icon) to execute the workflow.

 

Example 3: Grouped Variables with Reactive Mode

This example uses two grouped Global Variables with reactive mode. A Sequence Widget coordinates reading one variable and setting another, while a Slider Widget provides the value for the font_size variable.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. Two Global Variable widgets are configured within the "app" group:
    • language - Dropdown control (EN, ES), Auto-emit on variable change: Enabled (reactive mode), Group: "app"
    • font_size - Slider control (10-28), Auto-emit on variable change: Enabled (reactive mode), Group: "app"
  2. A Slider Widget triggers a Sequence Widget that:
    • Reads the "language" global variable via the "read" port
    • Sets the "font_size" global variable with the slider value via the "setValue" port
  3. Reactive mode forwards both values to the Object Widget, which combines them into a single object
  4. An Object to Text Widget converts the object to a JSON string
  5. A Text Widget displays the JSON object (e.g., {"language":"ES","font_size":90})

 

Example 4: Dynamic Message Generation with Global Variables

This example shows how widgets can directly use Global Variables. The Template String Widget reads both grouped variables (msg_prefix, msg_suffix from the "welcome_msg" group) and a standalone variable (department) from the Global Variables Panel, combining them with the user's name to generate a customized welcome message.


Drag the example onto the workspace to explore and experiment!



In this example:

  1. Global Variables provide the message components:

    • Grouped variables, accessed with: 
      $vars["welcome_msg.msg_prefix"]
$vars["welcome_msg.msg_suffix"]
    • Standalone variable, accessed with: 
      $vars.department

  2. The Text Widget supplies the name (e.g., "Maria").

  3. The Play Widget triggers the entire workflow.

  4. The Template String Widget combines:

    • the grouped variables,
    • the standalone variable,
    • and the input value

    with the following template:

    {{$vars["welcome_msg.msg_prefix"]}}
{{$vars.department}} team,
{{input.value}}!
{{$vars["welcome_msg.msg_suffix"]}}

  5. The final Text Widget displays the completed message.