We are commencing a series of articles dedicated to events in the JavaScript reporting tool. When developing JS projects, various events arise for objects such as a report, as well as visual components like the designer and the viewer. In this article, we will discuss report object events.

---

Reports events

onPrepareVariables

Report variables can be utilized both within the report and in queries to the data storage. You can populate variables or modify their values using the onPrepareVariables event.

This event is invoked at the outset of the report render, before populating the variables. Below is a list of event handler arguments:

{
	event: "PrepareVariables",
	sender: "Report",
	report: StiReport,

	preventDefault: boolean,
	async: boolean,
    
	variables: []
}

An example of replacing a value in a report variable:

report.onPrepareVariables = (args, callback) => {
	args.variables[0].value = "Replace value";
}

onBeginProcessData

A situation often arises where the connection to the data storage needs to be replaced before rendering a report. This can be easily accomplished using the onBeginProcessData event.

This event is invoked before requesting the data necessary to construct the report and enables you to modify the connection parameters accordingly. Below is a list of event handler arguments:

{
	sender: "Report",
	event: "BeginProcessData",
	report: StiReport,

	preventDefault: boolean,
	async: boolean,
    
	command: string,
	database: string,
	connection: string,

	headers: [],
	withCredentials: string,
    
	// Json
	pathData: string,
	tryParseDateTime: boolean,
	relationDirection: StiRelationDirection,

	// Xsd
	pathSchema: string,

	// Xml
	pathData: string,
	tryParseDateTime: boolean,
	relationDirection: StiRelationDirection,
    
	// Excel
	pathData: string,
	firstRowIsHeader: boolean,

	// OData
	connectionString: string,
	dataSource: string,
	collectionName: string,

	// Sql
	connectionString: string,
	dataSource: string,
	queryString: string,
	timeout: number,
	parameters: { name: string, value: string | number }[],
	escapeQueryParameters: boolean,

	// Gis
	pathData: string,
	separator: string,
	dataType: StiGisDataType,

	// Csv
	pathData: string,
	separator: string,
	codePage: number,

	// DBase
	pathData: string,
	codePage: number
}

Below is an example of replacing a connection string:

report.onBeginProcessData = (args) => {
	if (args.database == "MySQL")
		args.connectionString = "new connection string";
}

And also, here is an example of our own implementation of data retrieval:

report.onBeginProcessData = (args, callback) => {
    if (args.database == "MySQL"){
        args.preventDefault = true;

        var result = {
            success: true,

            rows: [
                ["value1", 1, false],
                ["value2", 1, true],
                ["value3", 2, false]
            ],
            columns: [
                "Column1_name",
                "Column2_name",
                "Column3_name"
            ],
            types:[
                "string",
                "int",
                "boolean"
            ]
        }

        // https://github.com/stimulsoft/DataAdapters.JS/
        callback(result);
    }
}

onEndProcessData

There are also situations when, after retrieving data, it needs to be adjusted or transformed. For example, creating custom datasets. This is easy to do using the onEndProcessData event.

This event is raised after the data has been received, but before the report-building process begins. List of event handler arguments:

{
    sender: "Report",
    event: "EndProcessData",
    report: StiReport,

    command: string,
    dataSource: string,
    connection: string,
    database: sgtring,

    result: DataSet|any
}

An example of adjusting data from the adapter:

report.onEndProcessData = (args) => {
    if (args.command == "ExecuteQuery" && args.dataSource == "Categories")
        args.result.rows.push(rowData) ;

    // https://github.com/stimulsoft/DataAdapters.JS/
}

onBeginRender

The event is called at the beginning of building a report template. For example, you can replace a value in a component before processing it:

report.onBeginRender = function (args) {
    const text = this.pages.getByIndex(0).components.getByIndex(0);
    const newValue = report.dictionary.variables.getByName("Variable2").value;
    text.text = newValue;
}

onRendering

The event is called during the creation of a report template, that is, when creating each new page of the template.
Below is the code for changing numeric values in text components:

report.onRendering = function (args) {
	const components = this.pages.getByIndex(0).components.list;

	for (let component of components) {
		if (component instanceof Stimulsoft.Report.Components.StiText) {
			const num = Number.parseFloat(component.text);
			if (!isNaN(num)) {
				component.text = String(num * 100);
			} else {
				console.log("The value is NaN");
			}
		}
	}
}

onEndRender

The event is raised at the end of the report template processing.
For example, after rendering a report, you can export it:

report.onEndRender = (args) => {
	report.exportDocumentAsync(function (data) {
		Stimulsoft.System.StiObject.saveAs(data, "Report.pdf", "application/pdf");
	}, Stimulsoft.Report.StiExportFormat.Pdf);
}

onExporting

This event is called before the report is exported. For example, you can display a message indicating that the report is ready for export:

report.onExporting = (args) => {
	console.log("The report is complected for exporting to ${args.exportFormat");
}

onExported

This event is called after the report is exported. For example, after finishing exporting a report, you can display a message indicating the completion of this process:

report.onExported = (args) => {
    const pages = report.renderedPages.list;
    console.log("PDF file contains " + pages.length + " pages");
}

onPrinting

The report may be sent for printing, in which case it can be modified using this event.
This event occurs when either report.print() or report.printToPdf() is called, allowing the report to be modified before printing.
For instance, you can remove an image from a report before printing.

report.onExported = (args) => {
    const pages = report.renderedPages.list;
    console.log("PDF file contains " + pages.length + " pages");
}

onPrinted

Another event occurs when printing a report, allowing you to modify a report that has already been converted into an HTML or PDF document, or implement your own printing method.
This event is raised when calling report.print() or report.printToPdf() after exporting to PDF or HTML, depending on the method called. Note!

The onPrinted event occurs after the report is exported, while the onPrinting event occurs after the print method is called, even before it is converted. Below is a list of event handler arguments:

{
	sender: "Report",
	event: "PrintReport",
	report: StiReport,

	preventDefault: boolean,
	async: boolean,

	data: string | number[]
}

An example of interrupting execution and implementing your own printing method:

report.onPrintReport = (args) => {
    args.preventDefault = true;

    var printData = args.data;
    myPrintingMethod(printData);
}

onRefreshing

If you need to make any changes when updating a report or dashboard, you can easily do so using the onRefreshing event.
This event occurs when you click the Refresh button in the viewer or when automatically refreshing using the report.refreshTime property.