# ReportBuilder

Generate PDFs using a template, parameters, and API data.

URL: https://webrad.atentor.com/docs/report-builder
Updated: 2026-11-07

WebReportBuilder · Nonvisual · Nonvisual · 3 events

## Quick start

Add **ReportBuilder1** in the Designer. Use the example in a page method.

```ts
// Declare Title as text in the report template.
ReportBuilder1.Parameters.SetValue('Title', 'Customer report');
ReportBuilder1.previewMode = 'modal';
ReportBuilder1.fileName = 'customers.pdf';
try {
  const result = await ReportBuilder1.GeneratePDF({
    parameters: { Title: 'Active customers' },
    fileName: 'customers.pdf',
  });
  console.log(result.pageCount, result.blob.size);
  // Generate() also displays the PDF at the chosen destination.
} catch (error) {
  Message(error instanceof Error ? error.message : String(error));
}
```

Load API data before generating. GeneratePDF() returns the PDF; Generate() also opens the selected presentation.

- Open the report designer and configure pages, elements, data sources, and parameters.
- Execute bound API operations before Generate() or GeneratePDF().
- Parameters.Set/Get use typed template names; SetValue/GetValue support templates loaded at runtime.
- LoadTemplate() loads JSON, a Blob, or a URL; SaveTemplate() exports JSON.
- previewMode selects modal, new tab, or download. ClosePreview() closes the modal presentation.
- OnGenerate allows parameter adjustments; OnSuccess delivers the result and OnError reports a failure.

## Inspector properties

Component options and defaults. Fields without runtime access are configured in the Inspector.

| Property / source | Type and options | Default | Runtime access |
| --- | --- | --- | --- |
| `name` — Name · Identity | `string` | `—` | name |
| `reportTemplate` — Report template · Report — Open the report designer to edit bands, fields, repeated records and parameters. | `report-template` — Editor: report-builder | `{"schemaVersion":1,"name":"Report","paper":{"size":"A4","orientation":"portrait","margins":{"top":15,"right":15,"bottom":15,"left":15}},"parameters":[],"bands":[{"id":"report-title","kind":"title","height":22,"elements":[{"id":"report-heading","name":"Title","type":"text","x":0,"y":0,"width":180,"height":12,"value":{"kind":"static","value":"My report"},"fontSize":22,"color":"#1e293b","bold":true,"align":"left"}]},{"id":"report-page-header","kind":"pageHeader","height":10,"elements":[]},{"id":"report-detail","kind":"detail","height":30,"elements":[]},{"id":"report-page-footer","kind":"pageFooter","height":10,"elements":[{"id":"report-page-number","name":"Page","type":"text","x":150,"y":0,"width":30,"height":8,"value":{"kind":"system","value":"pageNumber"},"fontSize":9,"color":"#64748b","bold":false,"align":"right"}]},{"id":"report-summary","kind":"summary","height":12,"elements":[]}]}` | reportTemplate |
| `previewMode` — Preview destination · Report — Show the generated PDF in a modal, open it in a new tab, or download it directly. | `enum` — `modal` `new-tab` `download` | `"modal"` | previewMode |
| `fileName` — PDF file name · Report | `string` | `"report.pdf"` | fileName |

## API in code

| Member | Signature | Access |
| --- | --- | --- |
| `Parameters` | `readonly Parameters: WebReportParameters<TParameters>;` | Read-only |
| `template` | `get template(): WebReportTemplate;` | Read and write |
| `reportTemplate` | `get reportTemplate(): WebReportTemplate;` | Read and write |
| `previewMode` | `get previewMode(): WebReportPreviewMode;` | Read and write |
| `fileName` | `get fileName(): string;` | Read and write |
| `busy` | `get busy(): boolean;` | Read-only |
| `OnGenerate` | `get OnGenerate(): WebReportEventHandler<this, WebReportGenerationOptions> \| null;` | Read and write |
| `OnSuccess` | `get OnSuccess(): WebReportEventHandler<this, WebReportResult> \| null;` | Read and write |
| `OnError` | `get OnError(): WebReportEventHandler<this, Error> \| null;` | Read and write |

### `bindApiClient`

method

```ts
bindApiClient(key: string, client: WebApiClient): void;
```

Generated code binds each component by stable model ID and by its authored name.

Example

```ts
ReportBuilder1.bindApiClient('ApiClient1', ApiClient1);
```

### `SaveTemplate`

method

```ts
SaveTemplate(): string;
```

Example

```ts
ReportBuilder1.SaveTemplate();
```

### `LoadTemplate`

method

```ts
LoadTemplate(value: WebReportTemplate | string | Blob): Promise<void>;
```

Example

```ts
await ReportBuilder1.LoadTemplate('https://app.example.com/template.report.json');
```

### `GeneratePDF`

method

```ts
GeneratePDF(options?: WebReportGenerationOptions): Promise<WebReportResult>;
```

Example

```ts
await ReportBuilder1.GeneratePDF({ fileName: 'report.pdf' });
```

### `Generate`

method

```ts
Generate(options?: WebReportGenerationOptions): Promise<WebReportResult>;
```

Example

```ts
await ReportBuilder1.Generate({ previewMode: 'modal' });
```

### `ClosePreview`

method

```ts
ClosePreview(): void;
```

Example

```ts
ReportBuilder1.ClosePreview();
```

### `dispose`

method

```ts
dispose(): void;
```

Example

```ts
// Call only when disposing of an instance whose lifecycle you control.
ReportBuilder1.dispose();
```

Inherited members (4)

| Member | Signature | Access |
| --- | --- | --- |
| `id` | `readonly id: string;` | Read-only |
| `name` | `readonly name: string;` | Read-only |

### `bindEvent`

method

```ts
bindEvent(eventName: string, handler: WebComponentEventHandler<this> | null): () => void;
```

### `emit`

method

```ts
emit(eventName: string, detail?: unknown): boolean;
```

## All Parameters methods

Declare parameters in the template before using them. Title is an example text parameter. Set/Get methods use generated types; SetValue/GetValue validate names from the template loaded at runtime.

| Member | Signature | Access |
| --- | --- | --- |
| `template` | `readonly template: () => WebReportTemplate;` | Read-only |
| `values` | `get values(): Readonly<TValues>;` | Read-only |

### `Set`

method

```ts
Set<K extends keyof TValues & string>(name: K, value: TValues[K]): void;
```

Example

```ts
ReportBuilder1.Parameters.Set('Title', 'Customer report');
```

### `SetValue`

method

```ts
SetValue(name: string, value: WebReportParameterValue): void;
```

Dynamic names for externally loaded templates; values still follow their declared types.

Example

```ts
ReportBuilder1.Parameters.SetValue('Title', 'Customer report');
```

### `Get`

method

```ts
Get<K extends keyof TValues & string>(name: K): TValues[K];
```

Example

```ts
console.log(ReportBuilder1.Parameters.Get('Title'));
```

### `GetValue`

method

```ts
GetValue(name: string): WebReportParameterValue;
```

Example

```ts
console.log(ReportBuilder1.Parameters.GetValue('Title'));
```

### `Clear`

method

```ts
Clear(name?: keyof TValues & string): void;
```

Example

```ts
ReportBuilder1.Parameters.Clear('Title');
// ReportBuilder1.Parameters.Clear(); // Restore all parameters.
```

### `reconcile`

method

```ts
reconcile(previous: WebReportTemplate, next: WebReportTemplate): void;
```

Retains only overrides whose names and declared types survive a template replacement.

Example

```ts
ReportBuilder1.Parameters.reconcile(ReportBuilder1.template, ReportBuilder1.template);
// The runtime reconciles parameters when switching templates.
```

## Events

Link methods in **Interaction**. [How to use events](https://webrad.atentor.com/docs/interactions).

### OnGenerate

[WebReportGenerationOptions](https://webrad.atentor.com/docs/types#webreportgenerationoptions) in `event.detail`

Signature and example

```ts
import type { WebReportBuilder, WebReportGenerationOptions } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async ReportBuilder1Generate(
    sender: WebReportBuilder,
    event: CustomEvent<WebReportGenerationOptions>,
  ): Promise<void> {
    console.log(event.detail);
  }
}
```

### OnSuccess

[WebReportResult](https://webrad.atentor.com/docs/types#webreportresult) in `event.detail` · `blob`, `pageCount`, `fileName`

Signature and example

```ts
import type { WebReportBuilder, WebReportResult } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async ReportBuilder1Success(
    sender: WebReportBuilder,
    event: CustomEvent<WebReportResult>,
  ): Promise<void> {
    console.log(event.detail);
    const { blob, pageCount, fileName } = event.detail;
    console.log(blob, pageCount, fileName);
  }
}
```

### OnError

`Error` in `event.detail`

Signature and example

```ts
import type { WebReportBuilder } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async ReportBuilder1Error(
    sender: WebReportBuilder,
    event: CustomEvent<Error>,
  ): Promise<void> {
    Message(event.detail.message);
  }
}
```