> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Template Builder

> Build report templates visually by assembling blocks instead of writing .tpl code manually, and let the builder generate it for you.

The Template Builder is a visual editor that lets you create report templates by assembling blocks — without writing `.tpl` code manually. It generates the template code automatically from your block configuration.

## Accessing the Template Builder

***

To open the Template Builder:

<Steps>
  <Step>
    Go to the **Templates** page and click the **Template Builder** button.
  </Step>

  <Step>
    The builder opens in a full-screen editor with three main areas: header, canvas, and Data Sources sidebar.
  </Step>
</Steps>

You can also edit an existing template in the builder by clicking on its name in the templates list (if it was originally created with the builder).

## Editor layout

***

### Header

The top bar contains:

* **Back** — returns to the templates list.
* **Template name** — inline editable text field.
* **Output format** selector — choose between XML, HTML, CSV, TXT, or PDF.

<Note>
  When **PDF** is selected, the generated template code uses HTML format. The output is rendered as HTML and converted to PDF at report generation time.
</Note>

* **View mode** toggle — switch between **Visual** (block editor) and **Code** (generated code preview).
* **Download .tpl file** — downloads the generated template code as a `.tpl` file.
* **Save** — validates blocks and saves the template.

### Canvas (Visual mode)

The main area where you build your template. It contains:

* **Blocks toolbar** — a palette of available block types at the top. Click a block type to add it to the canvas.
* **Block list** — the ordered list of blocks that compose your template. You can drag blocks to reorder them.

### Canvas (Code mode)

A read-only preview of the generated template code with syntax highlighting. Template expressions (`{{ }}`), tags (`{% %}`), and comments (`{# #}`) are color-coded. You can copy the code to clipboard or download it.

### Data Sources sidebar

A panel on the left showing your configured database connections. You can:

* Browse schemas and tables from your Data Sources.
* Click a field to automatically add a **Variable** block referencing that field.

<Note>
  The Data Sources sidebar only shows connections configured in the Data Sources section. If no connections are available, the panel will display a message to configure them first.
</Note>

## Block types

***

The builder provides 13 block types, each serving a specific purpose:

| Block             | Description                                                                                                                                             |   |                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | - | --------------------------------------- |
| **Text**          | Static text content (HTML, XML, CSV, or any plain text).                                                                                                |   |                                         |
| **Variable**      | Inserts a value from a data source field. Supports filters (e.g., `upper`, `lower`). Can reference data source, table, field, and index.                |   |                                         |
| **Loop**          | Iterates over a collection from a data source table. Requires an iterator name and an iterable source (e.g., `dataSource.table`). Accepts child blocks. |   |                                         |
| **Conditional**   | Renders child blocks based on a condition (e.g., `account.status == "active"`). Supports operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `&&`, \`          |   | \`. Optionally includes an else branch. |
| **Aggregation**   | Performs aggregate calculations: Sum, Count, Average, Min, Max, or Last Item by Group. Requires a source, field, and optional condition.                |   |                                         |
| **Calculation**   | Evaluates a mathematical expression (e.g., `value * 1.05`). Supports operators: `+`, `-`, `*`, `/`, `**` (power), `%` (modulo).                         |   |                                         |
| **Date/Time**     | Inserts a formatted date/time. Optionally references a date field from data; defaults to current server time if empty.                                  |   |                                         |
| **Counter**       | Increments or displays a named counter. Useful for row numbering. Can manage multiple counter names.                                                    |   |                                         |
| **Comment**       | Adds a comment that does not appear in the generated report output.                                                                                     |   |                                         |
| **Section**       | Groups child blocks under a named section title. Useful for organizing large templates.                                                                 |   |                                         |
| **With (Assign)** | Assigns the result of an expression to a variable name, which child blocks can reference.                                                               |   |                                         |
| **Expression**    | Inserts an inline expression rendered as `{{ expression }}`. Supports pipe filters.                                                                     |   |                                         |
| **Custom Tag**    | Renders a custom template tag (e.g., `include`, `load`). Accepts a tag name and optional arguments.                                                     |   |                                         |

## Working with blocks

***

### Adding blocks

* Click a block type in the **toolbar** at the top of the canvas, or
* Click a field in the **Data Sources sidebar** to add a Variable block automatically.

### Reordering blocks

Drag blocks using the drag handle to reorder them within the template.

### Configuring blocks

Each block has its own configuration form that appears inline. Fill in the required fields for the block type (e.g., source and field for Variable, condition for Conditional).

### Block options

Each block has additional options in its header:

* **Inline** — renders the block without a line break after it.
* **Trim whitespace** — removes surrounding whitespace from the block output.
* **Duplicate** — creates a copy of the block.
* **Delete** — removes the block from the template.

### Container blocks

Some blocks accept **child blocks** (Loop, Conditional, Section, With). You can add child blocks inside them to create nested template logic. Conditional blocks also support **else** children.

## Saving and downloading

***

When you click **Save**, the builder:

1. Validates all blocks for required fields and correct configuration.
2. Sends the blocks to the backend for code generation.
3. If backend generation fails, falls back to local code generation.
4. Saves the template with the generated `.tpl` file.

If validation errors are found, they are displayed as toast notifications indicating which block and field has the issue.

You can also **download** the generated `.tpl` file at any time using the **Download .tpl file** button in the header, without saving.

## Keyboard shortcuts

***

| Shortcut                     | Action |
| ---------------------------- | ------ |
| `Ctrl+Z` / `⌘+Z`             | Undo   |
| `Ctrl+Shift+Z` / `⌘+Shift+Z` | Redo   |