Event Handler
The reporting tool, along with the viewer and report designer, can trigger events on the client side, transfer them to the Python server for further processing, and receive a response prepared on the server. All actions are implemented in the event handler, eliminating the need for any additional functions to communicate between the client and server and transfer data. To handle a specific event, simply add the function name to the handler, and the specified function will be automatically called when the event occurs. Events can be called on both the JavaScript client side and the Python server side. If needed, you can add multiple functions of any type to the same event.
Calling a JavaScript event on the client side
To trigger a JavaScript event on the client side, add the function name as a string to the handler. All necessary data will be passed through the event arguments, which can be viewed in the section Reports Engine Events.
For example, after generating a report, you may want to display a message indicating the number of pages in the resulting document:
app.py |
from stimulsoft_reports.report import StiReport
report = StiReport() report.onAfterRender += 'afterRender' report.loadFile(url_for('static', filename='reports/SimpleList.mrt')) report.render()
|
report.html |
<script> function afterRender(args) { let pagesCount = args.report.renderedPages.count; alert("The report is rendered, pages: " + pagesCount); } </script>
|
In this example, you can obtain a JavaScript report object from the event arguments and read the number of pages in the document that was generated.
Information |
More information about the available functions and parameters of the JavaScript reporting tool can be found in the documentation for the Stimulsoft Reports.JS and Stimulsoft Dashboards.JS products.
|
Calling a Python event on the server side
To call a Python event, add the function name as a variable to the handler. All necessary data will be passed in the event arguments; the list of available arguments can be viewed in the Report Engine Events.
For example, before requesting data, you may need to adjust the password in the connection string:
app.py |
from stimulsoft_reports.events import StiDataEventArgs
def beginProcessData(args: StiDataEventArgs): args.connectionString = args.connectionString.replace('Pwd=;', 'Pwd=******;')
report = StiReport() report.onBeginProcessData += beginProcessData report.loadFile(url_for('static', filename='reports/SimpleList.mrt')) report.render()
|
In this example, you can retrieve and modify all the database connection parameters from the event arguments.
The event on the Python server side allows you to return a text message indicating successful completion or an error during event processing; this message will be displayed in the viewer or designer after the event concludes. To display an error message window, you must return the result of the StiResult.getError('Error message') function. To display a window with an information message, you can return the result of the StiResult.getSuccess('Info message') function or simply the string 'Info message'.
app.py |
from stimulsoft_reports import StiResult from stimulsoft_reports.designer import StiDesigner from stimulsoft_reports.events import StiReportEventArgs from stimulsoft_reports.report import StiReport
def saveReport(args: StiReportEventArgs): #StiResult.getError('An error occurred while saving.') #StiResult.getSuccess('The report was successfully saved.') return 'The report was successfully saved.'
designer = StiDesigner() designer.onSaveReport += saveReport
|
Information |
When an error occurs in the event handler, such as a failure to connect to the database or an error processing a file, an internal message will be displayed regardless of whether a message is defined in the component event.
|
Information |
The message dialog box will only appear when using the StiViewer or StiDesigner components. The reporting tool does not include visual forms, so event processing messages will be displayed in the browser console.
|
Calling several identical events
You can add an unlimited number of functions to the event handler; they will all be grouped by event type and called sequentially in the order they were added. For example, you might need to modify the SQL query on the JavaScript client side and adjust the connection string on the Python server side:
app.py |
from stimulsoft_reports.events import StiDataEventArgs
def beginProcessData(args: StiDataEventArgs): args.connectionString = args.connectionString.replace('Pwd=;', 'Pwd=;')
report = StiReport() report.onBeginProcessData += beginProcessData report.onBeginProcessData += 'beginProcessData' report.loadFile(url_for('static', filename='reports/SimpleList.mrt')) report.render()
|
viewer.html |
<script> function beginProcessData(args) { args.queryString = args.queryString.replace('TableName', 'Products') } </script>
|
Information |
Some events can only be triggered on the JavaScript client side and cannot be triggered on the Python server side. When adding a function to such an event, no error will occur, but the function will not be called. All supported options are listed in the section Report Engine Events.
|