WEBRAD / TECHNICAL REFERENCE

ReportBuilder

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

WebReportBuilderNonvisualNonvisual3 events

Quick start

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

// 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));
}

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 · ReportOpen 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 · ReportShow the generated PDF in a modal, open it in a new tab, or download it directly.	`enummodal` `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

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

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

Example

ReportBuilder1.bindApiClient('ApiClient1', ApiClient1);

`SaveTemplate`

method

SaveTemplate(): string;

Example

ReportBuilder1.SaveTemplate();

`LoadTemplate`

method

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

Example

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

`GeneratePDF`

method

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

Example

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

`Generate`

method

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

Example

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

`ClosePreview`

method

ClosePreview(): void;

Example

ReportBuilder1.ClosePreview();

`dispose`

method

dispose(): void;

Example

// 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

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

`emit`

method

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

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

Example

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

`SetValue`

method

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

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

Example

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

`Get`

method

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

Example

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

`GetValue`

method

GetValue(name: string): WebReportParameterValue;

Example

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

`Clear`

method

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

Example

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

`reconcile`

method

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

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

Example

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

Events

Link methods in Interaction. How to use events.

OnGenerate

WebReportGenerationOptions in event.detail

Signature and example

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 in event.detail · blob, pageCount, fileName

Signature and example

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

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);
  }
}