> ## 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.

Use Template Builder to create or maintain a Template visually. The builder converts blocks into `.tpl` code, so operators can define report structure without writing the Template file manually.

## Objective

***

Build a Template from visual blocks and save it for future Report generation.

For example, a monthly transaction Template can use fixed text for the header, a **Loop** for each transaction row, **Variable** blocks for fields such as amount and date, and an **Aggregation** block for the total.

## When to use

***

Use Template Builder when:

* operators need to create a Template without editing `.tpl` code;
* a Template Builder Template needs to be maintained visually;
* the report structure depends on fields, loops, conditions, or totals from a Data Source;
* the team wants to download the generated `.tpl` file after building it.

Use `.tpl` upload instead when a technical team already created and reviewed the Template outside the Console.

## Before you start

***

Confirm:

* at least one relevant Data Source exists if the Template needs database fields. It can be an internal source already configured for the environment or an external source added from **Data Sources**;
* the Data Source was tested when connection health or schema visibility is uncertain, so its tables and fields are available in the sidebar;
* the expected output format is known: XML, HTML, CSV, TXT, or PDF;
* the operator knows the report structure, such as required header, rows, totals, or conditional sections.

<Note>
  Blocks define the output structure. Filters applied during Report generation define which records enter that structure.
</Note>

## Step by step

***

<Steps>
  <Step title="Open the builder">
    Go to the **Templates** page and click **Template Builder**.
  </Step>

  <Step title="Name the Template">
    Edit the Template name in the header. Use a name that operators can identify during report generation.
  </Step>

  <Step title="Choose the output format">
    Select XML, HTML, CSV, TXT, or PDF.

    <Note>
      When **PDF** is selected, the generated template code uses HTML format and is converted to PDF during report generation.
    </Note>
  </Step>

  <Step title="Add blocks to the canvas">
    Use the blocks toolbar to add structure. Common blocks are **Text**, **Variable**, **Loop**, **Conditional**, and **Aggregation**.
  </Step>

  <Step title="Connect fields from Data Sources">
    Use the Data Sources sidebar to browse schemas, tables, and fields. Click a field to add a **Variable** block for that field.
  </Step>

  <Step title="Review generated code when needed">
    Switch from **Visual** to **Code** to inspect the generated `.tpl` preview. The code view is for review and copy/download, not manual editing.
  </Step>

  <Step title="Save the Template">
    Click **Save**. The builder validates required block fields, generates `.tpl` code, and saves the Template.
  </Step>
</Steps>

## Field guide

***

### Builder-level fields and controls

| Field or control       | What it does                                                                                                                      | Example                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| **Template name**      | Required name in the builder header. It maps to `name` and becomes the saved Template label and generated `.tpl` filename prefix. | `Monthly transaction CSV`     |
| **Output format**      | Required format. Use `xml`, `html`, `csv`, `txt`, or `pdf`. When `pdf` is selected, code generation uses HTML internally.         | `pdf`                         |
| **Visual**             | Block editor mode for assembling the Template. Technical state: `viewMode = visual`.                                              | Use while arranging blocks    |
| **Code**               | Read-only preview of generated `.tpl` code. Technical state: `viewMode = code`.                                                   | Review generated `.tpl`       |
| **Download .tpl file** | Downloads the generated `.tpl` without saving a new Template.                                                                     | `monthly-transaction-csv.tpl` |
| **Save**               | Validates blocks, generates `.tpl` code, and uploads or updates the Template. Requires a nonblank name and at least one block.    | Save after blocks are valid   |

### Block field guide

| Block             | Fields to configure                                                                                                                  | Effect                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Text**          | **Content** (`content`)                                                                                                              | Renders fixed text such as CSV headers, XML tags, or HTML fragments.                                        |
| **Variable**      | **Data Source**, **Table**, **Field**, **Index (optional)**, **Filters** (`dataSource`, `table`, `field`, `index`, `filters[]`)      | Inserts a field value. Inside a parent **Loop**, **Data Source** can be auto-filled from the loop iterator. |
| **Loop**          | **Iterator name** and **Iterable source** (`iteratorName`, `iterableSource`)                                                         | Repeats child blocks over a collection. Use `dataSource.table` format for the iterable source.              |
| **Conditional**   | **Condition** and **Include else block** (`condition`, `hasElse`)                                                                    | Renders child blocks only when the condition is true; optional else content can render when false.          |
| **Aggregation**   | **Aggregation type**, **Source**, **Field**, optional grouping/order/result fields (`aggregationType`, `source`, `aggregationField`) | Produces totals, counts, averages, min/max, or **Last Item by Group** values from a source collection.      |
| **Calculation**   | **Expression** (`expression`)                                                                                                        | Renders a calculated value. Supported operators shown in the UI include `+`, `-`, `*`, `/`, `**`, and `%`.  |
| **Date/Time**     | **Format** and **Date source** (`format`, `dateSource`)                                                                              | Formats a date value, for example `YYYY-MM-DD` from `transaction.createdAt`.                                |
| **Counter**       | **Mode**, **Counter name**, and **Counter names** (`counterMode`, `counterName`, `counterNames[]`)                                   | **Increment** advances one counter. **Display** outputs one or more counters.                               |
| **Comment**       | **Comment** (`commentText`)                                                                                                          | Stores an internal Template note and does not appear in the final Report.                                   |
| **Section**       | **Section title** (`sectionTitle`)                                                                                                   | Groups child blocks to organize larger Templates.                                                           |
| **With (Assign)** | **Variable name** and **Assignment expression** (`variableName`, `assignment`)                                                       | Creates a reusable variable from an expression for child blocks.                                            |
| **Expression**    | **Expression** (`inlineExpression`)                                                                                                  | Renders an inline expression such as `item.name\|upper`.                                                    |
| **Custom Tag**    | **Tag name** and **Tag arguments** (`tagName`, `tagArgs`)                                                                            | Emits an advanced Template tag such as `include` with arguments like `"header.html"` or `key=value`.        |

## Block types

***

| Block             | What it represents in practice                                                       |
| ----------------- | ------------------------------------------------------------------------------------ |
| **Text**          | Fixed content that always appears in the output, such as a header or label.          |
| **Variable**      | A value from a data source field, such as document number, amount, or status.        |
| **Loop**          | A repeated section, such as one row for each transaction.                            |
| **Conditional**   | Content that appears only when a rule is true, such as `account.status == "active"`. |
| **Aggregation**   | A total, count, average, min, max, or last item by group.                            |
| **Calculation**   | A calculated value, such as `value * 1.05`.                                          |
| **Date/Time**     | A formatted date or time value.                                                      |
| **Counter**       | A row number or sequence value.                                                      |
| **Comment**       | Internal Template note that does not appear in the generated Report.                 |
| **Section**       | A named group of blocks for organizing larger Templates.                             |
| **With (Assign)** | A reusable variable created from an expression.                                      |
| **Expression**    | An inline expression rendered into the output.                                       |
| **Custom Tag**    | A custom Template tag when advanced Template syntax is needed.                       |

## Working with blocks

***

* Click a block type in the toolbar to add it to the canvas.
* Drag blocks to reorder the output.
* Configure each block inline. For example, a **Variable** needs a source and field, while a **Conditional** needs a condition.
* Use **Inline** when the block should render without a line break after it.
* Use **Trim whitespace** to remove extra spaces around block output.
* Use **Duplicate** to copy a configured block.
* Use **Delete** to remove a block from the Template.

Container blocks such as **Loop**, **Conditional**, **Section**, and **With** can hold child blocks. Use them when the output needs repeated or grouped content.

## Expected result

***

After saving, the Template appears on the **Templates** page and can be selected in the **Generate Report** wizard. You can also download the generated `.tpl` file from the builder.

## Common errors and care points

***

<AccordionGroup>
  <Accordion title="No Data Sources appear in the sidebar">
    The sidebar only shows configured Data Sources. If the expected internal source is not listed, confirm setup with the Reporter administrator. If the report needs an external database, add and test that Data Source before using database fields in the Template.
  </Accordion>

  <Accordion title="Required block fields are missing">
    The builder validates blocks during save. If a block is missing a source, field, condition, or expression, fix that block before saving.
  </Accordion>

  <Accordion title="Using filters inside the wrong part of the workflow">
    Template blocks define the file structure. Report filters are selected later during report generation and decide which records enter the output.
  </Accordion>

  <Accordion title="Choosing PDF without understanding the generated code">
    PDF output is generated from HTML. Build the Template as HTML-compatible content when the final output format is PDF.
  </Accordion>
</AccordionGroup>

## Next steps

***

* Use [Generate a Report](/en/lerian-console/reporter-console/generating-a-report) to test the Template with real filters.
* Use [Update a Template](/en/lerian-console/reporter-console/updating-a-template) to edit the Template later.
* Use [Add a Template](/en/lerian-console/reporter-console/adding-template) if you need to upload a prepared `.tpl` file instead.

<Card title="API equivalent" type="warning" horizontal>
  There is no separate API endpoint for the visual builder. Use [Upload template endpoint](/en/reference/reporter/upload-template) with a prepared `.tpl` file.
</Card>