Reports and Dashboards for JS > Engine

Reports and Dashboards for JS > Engine > Report Events

Report Events

Information

Since dashboards and reports use the same unified template format - MRT, methods for loading the template and working with data, the word “report” will be used in the documentation text.

In order to write interactive applications it is needed to respond to changes in the application. The event system which is represented in StiReport object can be used for this. The following events exist:

onPrepareVariables

Asynchronous event is called before filling in the variables in the report at the beginning of the report rendering. The event handler argument “event” is an object with the next fields:

Name	Description
sender	The identifier of the component, which initiated this event.
event	a string ID for the current event. By default, the value is set to PrepareVariables.
report	a report object StiReport.
preventDefault	a flag to prevent further processing of the event. By default, the value is set to false.
async	a flag is used to provide the ability to stop the execution of the event before the callback function is executed. By default, the value is set to false.

viewer.html

...

report.onPrepareVariables = (args, callback) => {

args.variables[0].value = "Replace value";

}

...

onBeginProcessData

Asynchronous event is called before requesting the data for the report. The event handler argument “event” is an object with the next fields:

Name	Description
sender	The identifier of the component, which initiated this event.
event	a string ID for the current event. By default, the value is set to BeginProcessData.
report	a report object StiReport.
preventDefault	a flag to prevent further processing of the event. By default, the value is set to false.
async	a flag is used to provide the ability to stop the execution of the event before the callback function is executed. By default, the value is set to false.
command	a string ID for the current command. Can have values "TestConnection" and "ExecuteQuery" to call the command to test a connection and data acquisition respectively.
database	a string name of the current database.
connection	the name of the current connection to a data source, specified in report template.
headers	an array of the query headers.
withCredentials	an argument is used to provide the ability to set a cookies in the query.
connectionString	a connection string to the data source for a report.
dataSource	the name of the current data source, specified in the report template. It is set only for SQL data sources.
queryString	a string with the SQL query to the database for retrieving data. Used only with the command = "ExecuteQuery".
timeout	an argument is used to provide the ability to define the seconds of the query timeout.
parameters	a list of the query parameters.
escapeQueryParameters	a flag is used to provide the ability to use the escaped part of the request. By default, the value is set to true.
pathData	an argument is used to provide the ability to define a path to data file.
tryParseDateTime	a flag is trying to parse data as DateTime.
relationDirection	an argument is used to provide the ability to change the direction of the relation between data sources.
pathSchema	an argument is used to provide the ability to define a path to XSD files.
firstRowIsHeader	a flag is used to provide the ability to use a first row as data header in Excel data source.
collectionName	a string collection name of the OData data source.
separator	a string separator of the CSV data source.
dataType	an argument is used to provide the ability to set the data type of the GIS data source.
codePage	an argument is used to provide the ability to set a code page of the CSV or DBF data source.

viewer.html

...

//Replace connection string

report.onBeginProcessData = (args) => {

if (args.database == "MySQL")

args.connectionString = "new connection string";

}

...

//Add a some data

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

Is called after retrieving data for the report. The event handler argument “event” is an object with the next fields:

Name	Description
sender	The identifier of the component, which initiated this event.
event	a string ID for the current event. By default, the value is set to EndProcessData.
report	a report object StiReport.
command	a string ID for the current command. Can have values "TestConnection" and "ExecuteQuery" to call the command to test a connection and data acquisition respectively.
dataSource	the name of the current data source, specified in the report template. It is set only for SQL data sources.
connection	the name of the current connection to a data source, specified in report template.
database	a string name of the current database.
result	a result dataset in a specific JSON format. It has two collections – columns and rows, with descriptions of columns and rows of data sources.

viewer.html

...

report.onEndProcessData = (args) => {

if (args.command == "ExecuteQuery" && args.dataSource == "Categories")

args.result.rows.push(rowData) ;

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

}

...

onBeginRender

Is called at the beginning of the report rendering. This is not relevant for the dashboards.

onRendering

Is called at the report is rendering when each report page is created. This is not relevant for the dashboards.

onEndRender

Is called at the ending of the report rendering. This is not relevant for the dashboards.

onExportingRender

Is called before a report export is started.

onExportedRender

Is called after a report export is ended.

onPrinting

Is called when report.print() or report.printToPdf() method is invoked. This is not relevant for the dashboards.

viewer.html

...

//Remove image before report printing

report.onPrintReport = () => {

var page = report.renderedPages.getByIndex(0);

var image = page.components.getByName("Image1");

if (image)

page.components.remove(image);

}

...

onPrinted

Asynchronous event is called when report.print() or report.printToPdf() method is invoked after a report is exported to Html or PDF file (depends on method type). This is not relevant for the dashboards. The event handler argument “event” is an object with the next fields:

Name	Description
sender	The identifier of the component, which initiated this event.
event	string ID for the current event. By default, the value is set to Printed.
report	a report object StiReport.
preventDefault	a flag to prevent further processing of the event. By default, the value is set to false.
async	a flag is used to provide the ability to stop the execution of the event before the callback function is executed. By default, the value is set to false.
data	export data to the string or byte array representation.

viewer.html

...

//Stop to report print and define a custom print method

report.onPrintReport = (args) => {

args.preventDefault = true;

var printData = args.data;

myPrintingMethod(printData);

}

...

onRefreshing

Is called after a report is rendered if report.refreshTime property is set more than zero. Also, this event is called when Refresh button is clicked in the viewer.