Logic & Dynamic Binding

The editor provides a powerful expression and binding engine that lets you connect canvas elements directly to dynamic dataset fields, apply conditional display rules, transform text and numbers, and loop over collections.

1. Working with Variables

Variables insert dynamic text or numerical values into your document output at render time.

Inserting Variables

You can insert variables into your canvas through two methods:

1. Drag-and-Drop: Drag a Variable ({}) block directly from the Block Manager onto the canvas.
2. Slash Command (/): Type / inside any active text block to open the cascading path selector dropdown and choose a payload field.

Editing Variables

To configure an existing variable, click the Edit Logic button in the Style Manager or click the Data icon (🗄️) on the floating component toolbar. This opens the Edit Variable modal where you can configure:

• Variable Path: Select or edit the JSON key path mapping to your payload data.
• Default Value: Define fallback text to display if the resolved variable path is null, undefined, or empty (e.g., Guest).
• Segment Selection Index (atIndex): Specify an index number to extract a single item from an array path.

2. Formatting & Aggregation Reference

Depending on the variable type and path, you can apply custom data formatting options and mathematical aggregations directly inside the variable settings modal.

Aggregation Configuration (AggregationConfig)

When binding a variable to an array or list of values, you can aggregate the data using the following calculation methods:

Formatting Options (FormatOptions)

Apply display transformations for numbers, currency, dates, strings, and charts:

Number & Currency Formatting

• Decimals (decimals): Controls the number of decimal places to display.
• Separators: Customize thousandsSeparator (e.g., ,) and decimalSeparator (e.g., .).
• Number Abbreviation (abbreviate): Compacts large numbers using custom suffix labels (abbreviationThousands, abbreviationMillions, abbreviationBillions, abbreviationTrillions).
• Currency Symbol: Define currencySymbol (e.g., $, €) and set currencyPosition to "before" or "after".
• Percentage (percentage): Formats numbers as percentages (e.g., 0.15 renders as 15%).

Date & Duration Formatting

• Date Formats: Select standard presets via dateFormat or specify custom syntax using customDateFormat (e.g., YYYY-MM-DD).
• Durations: Convert numerical values into time durations using durationUnit (seconds, minutes, hours, days) and durationFormat (short vs. long).

Text Transformations

• Transform: Modify text case using uppercase, lowercase, capitalize, truncate, or render inline markdown.
• Truncate Length (truncateLength): Specifies character limits when transform is set to truncate.
• Encoding (encode): Enables URL or string encoding.

3. Dynamic Component Attributes & Images

Component settings inside the Right Inspector Panel featuring a Data icon (🗄️) can be bound dynamically to payload data paths instead of static values.

Setting Up Dynamic Images

To render dynamic images (such as user avatars, generated charts, or dynamic product photos):

1. Select an Image component on the canvas.
2. Locate the src field in the Right Inspector Panel.
3. Click the Data icon (🗄️) next to the src input field.
4. Select the variable path containing your hosted image URL string (e.g., {{user.avatar_url}} or data:image/svg+xml;...).

4. Conditional Logic

Conditional components allow you to show or hide document sections dynamically based on logical rules.

Adding Conditions

• Context Menu Wrapping: Click the More Options (...) menu on any supported canvas element and choose Wrap in Condition. This wraps the selected block in a conditional statement and keeps the False / Else branch hidden by default.
• Direct Block Insertion: Drag a Condition block directly from the Block Manager. Direct insertion keeps both the True and False / Else content blocks visible on the canvas by default.

Editing Conditions

Click the Edit Logic button or Data icon (🗄️) on a condition block to open the Edit Condition modal:

• Logical Operators: Toggle between AND, OR, and XOR logic for combining multiple rules.
• Adding Rules (+ Rule): Define single comparisons (e.g., name -> startsWith -> B).
• Adding Groups (+ Group): Create nested sub-conditions for complex multi-level logic operations.

5. Dynamic Collections & Tables

Collection blocks allow you to repeat visual layouts, list items, or table rows across dynamic data arrays.

Configuring Collections

Click the Edit Logic button or Data icon (🗄️) on a collection container or table block to configure iteration parameters:

• Variable Path: Select the array payload path to iterate over (e.g., items or invoice.line_items).
• Sorting (+ Sorting): Add sort criteria to arrange items by specific fields in ascending or descending order.
• Filters (Filter): Build item filter rules using the integrated condition builder (AND/OR/XOR rules and groups) to suppress specific array items from rendering.

Grouping Data

Grouping allows you to categorize dynamic collection items by a specific field—such as region, category, or status—and render them into distinct sections or sub-tables.

1. Enable Grouping on a Collection

To group your data source:

1. Open the Edit Collection modal for your target component.
2. In the Group By field, select or search for the property you want to group by (e.g., region).
3. Click Confirm.

2. Understanding the Grouped Data Structure

When grouping is applied, the Collection changes how it iterates over your dataset. Instead of iterating directly through individual records, the Collection now iterates through Group Objects.

Each group context exposes the following variables:

3. Binding Grouped Data in the Canvas

Once grouping is enabled, you can build grouped layouts by combining group headers with nested elements or tables.

1. Add Group Headers: Insert a text element at the top of your collection row and bind it to groupField and groupKey.

   Example text binding: {groupField}: {groupKey} $\rightarrow$ renders as region: North America

2. Render Grouped Items: Insert a Table or nested Collection inside the outer item block and set its data source path to items (Items (region)).

3. Bind Item Columns: Map table cells or child elements to the fields within items (e.g., sku, price, category).

Example Output

Given a dataset containing items across multiple regions, applying a group by region will automatically separate your records into categorized sub-tables:

Dynamic Tables

Applying a collection to a Table component automatically creates dynamic repeating rows that expand based on the length of the bound dataset.

6. Data Filters (data-filter)

A Data Filter is closely related to a dynamic collection, sharing the exact same sorting, filtering, and grouping engine. However, while a standard Collection loops over and repeats a visual DOM structure for every item in the dataset, a Data Filter processes an array and allows you to:

1. Assign the Result to a Variable: Store the filtered, sorted, or grouped array directly into the runtime context (e.g., root.myFilteredList) for use by other components, formulas, tables, or charts.
2. Display the Result: Output the resulting dataset directly into the document.

How It Compares to Collections

Configuring a Data Filter

To create and configure a Data Filter:

1. Insert a Filter component from the Blocks Manager onto the canvas or into your text flow.
2. Click the Edit Logic button or Data icon (🗄️) on the filter component to open the configuration modal:
   • Variable Path: Select the source array path to process (e.g., root.transactions or order.items).
   • Sorting (+ Sorting): Add sort rules to arrange records by specific fields in ascending or descending order.
   • Filters (Filter): Build condition rules (AND/OR/XOR) to isolate specific subsets of data (e.g., status == "completed" and amount > 500).
   • Grouping (Group By): Group the filtered items by categorical keys.
   • Assign Result To Variable: Enter a target variable name (e.g., highValueTransactions). The filtered output will be assigned to root.<variableName>.
3. Click Confirm.

Downstream Usage

Once a Data Filter assigns its result to a variable, you can reference the filtered dataset anywhere downstream in your document:

• Charts: Feed the filtered array directly into chart datasets without needing backend data reshaping.
• Formulas: Pass the filtered variable to calculation formulas (e.g., SUM(root.highValueTransactions, "amount")).
• Collections & Tables: Bind another visual collection or table directly to root.highValueTransactions.
• Text & Badges: Display counts or stats (e.g., root.highValueTransactions.length items matching criteria`).

7. Formulas

You can use the formula component to access the formula builder and perform complex calculations, which can also be stored as variables for reuse.

String Functions

Array & Statistical Functions

Mathematical Functions

In-Depth Guide: The MAP Function

The MAP function is one of the most powerful tools in the formula engine. It iterates across each element in an array (or properties in an object) and returns a newly transformed dataset.

Signature: MAP(array | object, 'FORMULA' | mapping)

MAP is essential for collection transformations, arithmetic reductions, and projecting data for charts:

1. Contextual Keywords in Expressions

Within the formula string (wrapped in quotes), reference the current element and index using intuitive contextual keywords:

• Element Aliases: item, val, value, element, el, _, or $
• Iteration Index (0-based): index or i

// Arithmetic on numbers or scalar items
MAP(root["Numbers"], 'val * 2')

// 1-based numbered list prefixing
MAP(root["Labels"], 'i + 1 + ". " + val')

// Accessing fields via element keywords
MAP(root["Items"], 'item.price * item.quantity')

2. Direct Property Shorthand

When iterating over an array of objects, each object's properties are automatically injected into the local evaluation scope. You can reference properties directly without needing item. prefixes:

// Automatically resolves 'Price' and 'Quantity' from each object
MAP(root["Line Items"], 'Price * Quantity')

// Concatenates fields directly from employee records
MAP(root["Employees"], 'FirstName + " " + LastName')

3. Built-In Function Application

Transform each element with any built-in formula function, either explicitly inside an expression or by passing the function name as shorthand:

// Explicit invocation using 'val'
MAP(root["Descriptions"], 'UPPER(val)')

// Function name shorthand
MAP(root["Names"], 'UPPER')

// Rounding an array of numbers
MAP(root["Amounts"], 'ROUND')

4. Object Projection & Chart Data Reshaping

The MAP function can construct new object shapes per item using object literal syntax or arrow notation (-> or =>). This is especially useful for formatting raw payload datasets into the structure required by Chart.js (such as Scatter coordinates or Bubble datasets):

Object Literal Syntax

// Scatter points: produces [{ x: ..., y: ... }, ...]
MAP(root["Records"], '{ x: item["Sales"], y: item["Profit"] }')

// Bubble points: produces [{ x: ..., y: ..., r: ... }, ...]
MAP(root["Campaigns"], '{ x: item.Spend, y: item.Conversions, r: item.ROI * 5 }')

// Key remapping
MAP(root["Categories"], '{ label: item.Title, value: item.Count }')

Arrow Syntax (-> or =>)

// Remap Name to label and Score to value
MAP(root["Users"], 'Name -> label, Score -> value')

5. Composition & Aggregation

MAP expressions can be combined with reduction and aggregation functions in a single statement:

// Calculate total order value across all line items
SUM(MAP(root["Items"], 'price * quantity'))

// Compute class average from student records
AVG(MAP(root["Students"], 'grade'))

// Create a comma-separated uppercase string
JOIN(MAP(root["Tags"], 'UPPER(name)'), ", ")

6. Storing Evaluation Results to Variables

Like all formula components, you can define a Target Variable Name (e.g. chartSeriesData). When set, the evaluated MAP result is saved onto root.<variableName> (e.g. root.chartSeriesData), allowing any downstream Chart, Table, or Data Filter to consume it directly.

Usage Example

data = {
  items: [1, 2, 3],
  multiplier: 2,
};

'JOIN(SORT(arr(CONCAT(UPPER("hello"), ": ", SUM(items) * multiplier), CONCAT(LOWER("WORLD"), ": ", AVG(2, 4, 6) + 1))), " | ")',


Output: "HELLO: 12 | world: 5"