Мы начинаем серию статей, посвященную событиям в генераторе отчетов для JavaScript. При разработке JS-проектов у таких объектов как отчет, а также визуальных компонентов – дизайнера и вьювера – возникают различные события. В этой статье мы поговорим о событиях объекта отчет.

---

События отчета

onPrepareVariables

Переменные отчета могут использоваться как в самом отчете, так и в запросах к хранилищу данных. Заполнить переменные или изменить их значения можно при помощи события onPrepareVariables.

Это событие вызывается в начале построения отчета перед заполнением переменных. Список аргументов обработчика событий:

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

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

Пример замены значения в переменной отчета:

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

onBeginProcessData

Нередко возникает ситуация, когда перед построением отчета следует заменить подключение к хранилищу данных. Это легко выполнить при помощи события onBeginProcessData.

Это событие вызывается перед запросом данных, необходимых для построения отчета, и позволяет изменить параметры подключения к ним. Список аргументов обработчика событий:

{
	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
}

Ниже представлен пример замены строки соединения (connection string):

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

А также пример собственной реализации получения данных:

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

Также бывают ситуации, когда после получения данных их следует скорректировать или преобразовать. Например, создать пользовательский наборов данных. Это легко выполнить при помощи события onEndProcessData.

Это событие вызывается после получения данных, но до начала процесса построения отчета. Список аргументов обработчика событий:

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

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

    result: DataSet|any
}

Пример корректировки данных от адаптера:

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

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

onBeginRender

Событие вызывается в начале построения шаблона отчета. Например, можно заменить значение в компоненте перед его обработкой:

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

Событие вызывается в процессе построения шаблона отчета, то есть, при создании каждой новой страницы шаблона.
Ниже представлен код изменения числовых значений в текстовых компонентах:

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

Событие вызывается в конце обработки шаблона отчета.
Например, после построения отчета, можно осуществить его экспорт:

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

onExporting

Это событие вызывается перед экспортом отчета. Например, можно отобразить сообщение о готовности отчета к экспорту:

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

onExported

Это событие вызывается после экспорта отчета. Например, после окончания экспорта отчета можно вывести сообщение о завершении этого процесса:

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

onPrinting

Отчет может быть отправлен на печать, и в этом случае его можно изменить при помощи этого события.
Это событие возникает при report.print() или report.printToPdf() и позволяет модифицировать отчет перед печатью.
Например, можно удалить изображение в отчете перед печатью:

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

onPrinted

Еще одно событие при печати отчета, которое позволяет изменить уже преобразованный отчет в документ HTML или PDF, или же реализовать свой способ печати.
Это событие возникает при вызове при вызове report.print() или report.printToPdf() после экспорта в PDF или HTML (зависит от вызываемого метода). Обратите внимание!

Событие onPrinted возникает после экспорта отчета, а событие onPrinting - после вызова метода печати, еще до его преобразования. Ниже представлен список аргументов обработчика событий:

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

	preventDefault: boolean,
	async: boolean,

	data: string | number[]
}

Пример прерывания выполнения и реализации собственного способа печати:

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

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

onRefreshing

Если необходимо что-либо изменить при обновлении отчета или дашборда, то это легко выполнить при помощи события onRefreshing.
Это событие возникает при нажатии кнопки Обновить (Refresh) во вьювере или при автоматическом обновлении с использованием свойства report.refreshTime.