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 Stimulsoft Report Viewer 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 occurs immediately after execution onPrepareVariables event of the StiReport object. 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

...

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

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

}

...

 

 

onBeginProcessData

 

Asynchronous event is called before requesting the data for the report. The event occurs immediately after execution onBeginProcessData event of the StiReport object. 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

viewer.onBeginProcessData = (args) => {

if (args.database == "MySQL")

args.connectionString = "new connection string";

}

...

 

//Add a some data

viewer.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 occurs immediately after execution onEndProcessData event of the StiReport object. 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

...

viewer.onEndProcessData = (args) => {

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

args.result.rows.push(rowData) ;

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

}

...

 

 

onPrintReport

 

Asynchronous event is called before printing the report. This is not relevant when viewing 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

a string ID for the current event. By default, the value is set to PrintReport.

report

a report for saving.

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.

printAction

a sting method name for printing.

 

viewer.html

...

//Remove image before report print

viewer.onPrintReport = (args) => {

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

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

if (image)

page.components.remove(image);

}

...

 

 

onBeginExportReport

 

Asynchronous event is called before export but after applying the export options. 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 BeginExportReport.

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.

action

the action, which initiated export event - StiExportAction.

settings

export report settings.

format

export report format. Can have the following values:

Stimulsoft.Report.StiExportFormat.Pdf,

Stimulsoft.Report.StiExportFormat.Excel2007,

Stimulsoft.Report.StiExportFormat.Word2007,

Stimulsoft.Report.StiExportFormat.Html,

Stimulsoft.Report.StiExportFormat.Html5,

Stimulsoft.Report.StiExportFormat.Document.

Stimulsoft.Report.StiExportFormat.Text,

Stimulsoft.Report.StiExportFormat.Csv,

Stimulsoft.Report.StiExportFormat.ImageSvg,

Stimulsoft.Report.StiExportFormat.Ppt2007,

Stimulsoft.Report.StiExportFormat.Odt,

Stimulsoft.Report.StiExportFormat.Ods.

formatName

name of a selected report export format corresponds to the name of the constants in format list.

fileName

an exporting file name.

openAfterExport

The flag indicates that a report will be exported in a new browser tab (the true value) or after export completed file saving will be invoked (the false value).

 

viewer.html

...

viewer.onBeginExportReport = function (args) {

switch (event.format) {

case Stimulsoft.Report.StiExportFormat.Html:

args.settings.zoom = 2; // Set zoom to 200%

break;

}

console.log("exporting");

}

...

 

 

onEndExportReport

 

Asynchronous event is called after export 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, it is set to EndExportReport.

fileName

an exporting file name.

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.

action

the action, which initiated export event - StiExportAction.

format

export report format. Can have the following values:

Stimulsoft.Report.StiExportFormat.Pdf,

Stimulsoft.Report.StiExportFormat.Excel2007,

Stimulsoft.Report.StiExportFormat.Word2007,

Stimulsoft.Report.StiExportFormat.Html,

Stimulsoft.Report.StiExportFormat.Html5,

Stimulsoft.Report.StiExportFormat.Document.

Stimulsoft.Report.StiExportFormat.Text,

Stimulsoft.Report.StiExportFormat.Csv,

Stimulsoft.Report.StiExportFormat.ImageSvg,

Stimulsoft.Report.StiExportFormat.Ppt2007,

Stimulsoft.Report.StiExportFormat.Odt,

Stimulsoft.Report.StiExportFormat.Ods.

formatName

name of a selected report export format corresponds to the name of the constants in format list.

fileName

an exporting file name.

openAfterExport

The flag indicates that a report will be exported in a new browser tab (the true value) or after export completed file saving will be invoked (the false value).

data

export data to the string or byte array representation.

 

viewer.html

...

viewer.onEndExportReport = (args) => {

args.fileName = "SampleFileName.txt";

}

...

 

 

onInteraction

 

Asynchronous event is called while interactive action of the viewer (dynamic sorting, collapsing, drill-down, applying of parameters) until processing values by the report generator. 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, it is set to Interaction.

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.

action

The identifier of the current interactive action can take the following values:

•Sorting - This action happens when using sorting columns;
•DrillDown - This action happens when using sorting columns;
•Collapsing - This action happens when using of collapsing report blocks.

 

viewer.html

...

viewer.onInteraction = (args) => {

if (args.action == "Variables")

args.variables["Variable1"] = "New Value";

}

...

 

 

onEmailReport

 

It is called before sending the report by email. This is not relevant when viewing 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

a string ID for the current event. By default, the value is set to EmailReport.

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.

report

a report object StiReport.

settings

export email settings.:
email - address of the recipient;

subject - email subject;

message - email message.

format

export report format. Can have the following values:

Stimulsoft.Report.StiExportFormat.Pdf,

Stimulsoft.Report.StiExportFormat.Excel2007,

Stimulsoft.Report.StiExportFormat.Word2007,

Stimulsoft.Report.StiExportFormat.Html,

Stimulsoft.Report.StiExportFormat.Html5,

Stimulsoft.Report.StiExportFormat.Document.

Stimulsoft.Report.StiExportFormat.Text,

Stimulsoft.Report.StiExportFormat.Csv,

Stimulsoft.Report.StiExportFormat.ImageSvg,

Stimulsoft.Report.StiExportFormat.Ppt2007,

Stimulsoft.Report.StiExportFormat.Odt,

Stimulsoft.Report.StiExportFormat.Ods.

formatName

name of a selected report export format corresponds to the name of the constants in format list.

fileName

an exporting file name.

data

export data to the string or byte array representation.

 

viewer.html

...

viewer.onEmailReport = (args, callback) => {

args.async = true;

 

var emailAddress = args.settings.email;

var emailMessage = args.settings.message;

var emailSubject = args.settings.subject;

var emailAttachmentFileName = args.fileName;

var emailAttachment = args.data;

sendEmail(emailAddress, emailMessage, emailSubject, emailAttachmentFileName, emailAttachment);

 

setTimeout(() => {

callback();

}, 5000);

}

...

 

 

onDesignReport

 

It is called by pressing the Design button. The event handler argument “event” is an object with the following fields:

 

Name

Description

sender

The identifier of the component, which initiated this event.

event

a string ID for the current event, by default, it is set to DesignReport.

report

a report for designing.

 

viewer.html

...

var viewerOptions = new Stimulsoft.Viewer.StiViewerOptions();

viewerOptions.toolbar.showDesignButton = true;

var viewer = new Stimulsoft.Viewer.StiViewer(viewerOptions, "StiViewer", false);

viewer.renderHtml("content");

 

viewer.onDesignReport = (args) => {

var viewerDiv = document.getElementById("content");

viewerDiv.innerHTML = "";

var designerOptions = new Stimulsoft.Designer.StiDesignerOptions();

designerOptions.appearance.fullScreenMode = true;

var designer = new Stimulsoft.Designer.StiDesigner(designerOptions, "StiDesigner", false);

designer.renderHtml("content");

 

designer.report = args.report;

}

...

 

 

onShowReport

 

Asynchronous event is called after a report is rendered before its displaying in the viewer. The event handler argument “event” is an object with the following fields:

 

Name

Description

sender

The identifier of the component, which initiated this event.

event

a string ID for the current event, by default, it is set to ShowReport.

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

...

viewer.onShowReport = function (args) {

console.log("showing");

}

...

 

onOpenReport

 

Asynchronous event that provides the ability to use custom method of opening templates. The event is called before the dialog box is opened and before report is assigned to the viewer. The event handler argument “event” is an object with the following fields:

 

Name

Description

sender

The identifier of the component, which initiated this event.

event

a string ID for the current event, by default, it is set to OpenReport.

report

a report object StiReport.

preventDefault

a flag to prevent further processing of the event. By default, the value is set to true.

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

...

viewer.onOpenReport = (args) => {

args.async = true;

args.report = anotherReport;

callback();

}

...

 

 

onOpenedReport

 

Asynchronous event that provides the ability to change of the report before it is assigned to the viewer. The event is called after report has been opened and before report is assigned to the viewer. The event handler argument “event” is an object with the following fields:

 

Name

Description

sender

The identifier of the component, which initiated this event.

event

a string ID for the current event, by default, it is set to OpenedReport.

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

...

viewer.onOpenedReport = (args) => {

if (args.report.reportAuthor != "Stimulsoft") {

args.preventDefault = true;

window.alert("report.reportAuthor == " + args.report.reportAuthor);

}

}

...