In this article, we present a comprehensive guide to viewer events in the JS reporting tool, encompassing their detailed descriptions, lists of arguments, and much more. In the last article we talked about report events, and in this one we’ll talk about viewer events.

---

Viewer events

onPrepareVariables

The event is triggered at the beginning of report construction, before populating the variables in the report. It occurs immediately after processing the onPrepareVariables event on the StiReport instance. Below is the list of event handler arguments:

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

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

An example of replacing a variable value:

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

onBeginProcessData

The event is triggered before requesting the data needed to build the report. It occurs immediately after processing the onBeginProcessData event on the StiReport instance. Below is a list of event handler arguments:

{
    sender: "Viewer",
    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:

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

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

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

The event is triggered after receiving the data necessary to build the report. It occurs immediately after processing the onEndProcessData event on the StiReport instance. Below is a list of event handler arguments:

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

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

    result: DataSet|any
}

An example of adjusting data from the adapter:

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

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

onPrintReport

It is used to modify the report before printing or to implement custom printing functionality.
The event is triggered before the report is printed. Below is a list of event handler arguments:

{
    sender: "Viewer",
    event: "PrintReport",
    report: StiReport,
    
    preventDefault: boolean,
    async: boolean
    
    printAction: string,
}

An example of deleting a picture before printing:

viewer.onPrintReport = (args) => {
    var page = args.report.renderedPages.getByIndex(0);
    var image = page.components.getByName("Image1");
    if (image)
        page.components.remove(image);
}

onBeginExportReport

It is used to adjust export settings or modify the report before exporting.
The event is triggered before the report is exported, but after the export settings specified in the dialog box have been set. Below is a list of event handler arguments:

{
    sender: "Viewer",
    event: "BeginExportReport",
    report: StiReport
    
    preventDefault: boolean,
    async: boolean,
    
    action: StiExportAction,
    settings: IStiDashboardExportSettings | StiExportSettings,
    format: StiExportFormat,
    formatName: string,
    fileName: string,
    openAfterExport: boolean,
}

An example of adjusting export parameters:

viewer.onBeginExportReport = (args) => {
    if (args.format == Stimulsoft.Report.StiExportFormat.Pdf)
        args.settings.imageQuality = 0.5;
}

onEndExportReport

It is used to implement file saving independently.
The event is triggered after the report is exported but before the file is saved. Below is a list of event handler arguments:

{
    sender: "Viewer",
    event: "BeginExportReport",
    report: StiReport,
    
    preventDefault: boolean,
    async: boolean,
    
    action: StiExportAction,
    format: StiExportFormat,
    formatName: string,
    fileName: string,
    openAfterExport: boolean,
    data: string | number[]
}

An example of changing the name of an exported file:

viewer.onEndExportReport = (args) => {
    args.fileName = "SampleFileName.txt";
}

onInteraction

The event is triggered before interactivity takes place. Below is a list of event handler arguments:

{
    sender: "Viewer",
    event: "Interaction",
    report: StiReport,
    
    preventDefault: boolean,
    async: boolean,
    
    action: string,
    variables,
    sortingParameters,
    collapsingParameters,
    drillDownParameters,
    filteringParameters
}

An example of replacing a variable value:

viewer.onInteraction = (args) => {
    if (args.action == "Variables")
        args.variables["Variable1"] = "New Value";
}

onEmailReport

It is used to send an exported report via email.
The event is triggered before the report is sent via email. Below is a list of event handler arguments:

{
    sender: "Viewer",
    event: "EmailReport",
    report: StiReport,

    settings: {
        email: string;
        subject: string;
        message: string;
    },
    format: StiExportFormat,
    formatName: string,
    fileName: string,
    data: number[] | string
}

To enable the button, you need to set the following parameter:

viewerOptions.toolbar.showSendEmailButton = true;

An example of sending email:

viewer.onEmailReport = (args) => {
    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);
}

onDesignReport

It is used to display the designer and transfer the report template.
The event is triggered when the Design button is clicked. Below is a list of event handler arguments:

{
    sender: "Viewer",
    event: "DesignReport",
    report: StiReport
}

To enable the button, you need to set the following parameter:

viewerOptions.toolbar.showDesignButton = true;

An example of deleting a viewer, creating a designer and sending a report to the designer:

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

It is used to modify the report before displaying it in the viewer.
The event is triggered after the report is built but before it is displayed in the viewer. Below is a list of event handler arguments:

{
    sender: "Viewer",
    event: "ShowReport",
    report: StiReport,

    preventDefault: boolean,
    async: boolean
}

onOpenReport

It is used to implement your own method of opening templates.
The event is triggered before the report file selection dialog box opens and before it is sent to the viewer. Below is a list of event handler arguments:

{
    sender: "Viewer",
    event: "OpenReport",
    report: StiReport,
    
    preventDefault: boolean,
    async: boolean
}

To enable the button, you should set the following parameter:

viewerOptions.toolbar.showOpenButton = true;

An example of interrupting the call of a dialog box and passing its template:

viewer.onOpenedReport = (args) => {
    args.preventDefault = true;
    args.async = true;

    args.report = anotherReport;
    callback();
}

onOpenedReport

It is used to modify the report before transmitting it to the viewer.
The event is triggered after the report is opened but before it is sent to the viewer. Below is a list of event handler arguments:

{
    sender: "Viewer",
    event: "OpenedReport",
    report: StiReport,
    
    preventDefault: boolean,
    async: boolean
}

To enable the button, you need to set the following parameter:

viewerOptions.toolbar.showOpenButton = true;

An example of interrupting the opening of a report if the reportAuthor property is not equal to 'Stimulsoft':

viewer.onOpenedReport = (args) => {
    if (args.report.reportAuthor != "Stimulsoft") {
        args.preventDefault = true;
        window.alert("report.reportAuthor == " + args.report.reportAuthor);
    }
}