Working with Report Variables
The report generator allows using variables in expressions, queries, filters, and other report elements. It also supports the preview and modification of variable values from code before the report is generated.
Report template variable values
The report generator provides easy access to variables within a report template through the data dictionary. To achieve this, define the onBeforeRender event for the report object, where a JavaScript report object will be passed in the event arguments on the client-side. A detailed description of available argument values can be found in the Report Engine Events section.
To access a report variable, use the JavaScript function getByName() on the collection of variables within the report’s data dictionary. To change a variable’s value, simply assign a new value to its value property; there is no need to check the variable's type, as type conversion will be handled automatically. For example, to change the string and integer values of specific variables:
app.py |
from stimulsoft_reports.report import StiReport
report = StiReport() report.onBeforeRender += 'beforeRender' report.loadFile(url_for('static', filename='reports/SimpleList.mrt')) report.render()
|
report.html |
<script> function beforeRender(args) { let report = args.report;
let variableString = report.dictionary.variables.getByName("VariableString"); variableString.value = "Text value";
let variableInt = report.dictionary.variables.getByName("VariableInt"); variableInt.value = "20"; } </script>
|
Information |
The variable values will be changed in the report template, and if the template is subsequently saved, these changes will be saved in the file. To modify variable values without changes the template, you can use the onPrepareVariables event, which is triggered when preparing variable values before generating the report.
|
Direct access to variables in the report template on the Python server-side isn’t provided.
Variable values when generating a report
The report generator allows easy access to variables before the report is built. To achieve this, define the onPrepareVariables event for the report object. The event arguments will contain a collection of report variables with their types and values. If a variable is initialized as an expression, the evaluated value of the expression will be included in the collection. A detailed description of available argument values can be found in the Report Engine Events section.
In the client-side JavaScript event, the collection of variables is represented as an array of objects containing the variable name, type, and value. It is permissible to change variable values, but the new value’s type must match the type of the variable being modified.
app.py |
from stimulsoft_reports.report import StiReport
report = StiReport() report.onPrepareVariables += 'prepareVariables' report.loadFile(url_for('static', filename='reports/SimpleList.mrt')) report.render()
|
report.html |
<script> function prepareVariables(args) { args.variables = [ { name: "VariableString", type: "String", value: "Text value" }, { name: "VariableInt", type: "Int32", value: 20 } ]; </script>
|
In the Python server-side event, the collection of variables is represented as a dictionary of StiVariable objects, where each object contains the variable’s name, type, and value. The dictionary key corresponds to the name of the report variable.
app.py |
from stimulsoft_reports.report import StiReport from stimulsoft_reports.events import StiVariablesEventArgs
def prepareVariables(args: StiVariablesEventArgs): variableName = args.variables['Variable1'].name variableType = args.variables['Variable1'].typeName variableValue = args.variables['Variable1'].value
report = StiReport() report.onPrepareVariables += prepareVariables report.loadFile(url_for('static', filename='reports/SimpleList.mrt')) report.render()
|
It is allowed to change variable values, but the new value’s type must match the type of the variable being modified. To change the value, simply assign the new value to the variable’s value property, for example:
app.py |
from stimulsoft_reports.events import StiVariablesEventArgs
def prepareVariables(args: StiVariablesEventArgs): args.variables['VariableString'].value = 'Value from Server-Side' args.variables['VariableInt'].value = 123 args.variables['VariableDecimal'].value = 123.456
|
Variables of type DateTime are passed as datetime objects. To change its value, simply assign a new datetime object, for example:
app.py |
from datetime import datetime from stimulsoft_reports.events import StiVariablesEventArgs
def prepareVariables(args: StiVariablesEventArgs): args.variables['VariableDateTime'].value = datetime.today()
|
Variables of type Range are passed as a dictionary with two keys: from and to. To access and modify the values of a Range variable, use these keys. The format of each of the two values is the same as for a simple variable. For example, to change the values of a variable of type StringRange:
app.py |
from stimulsoft_reports.events import StiVariablesEventArgs
def prepareVariables(args: StiVariablesEventArgs): args.variables['VariableStringRange'].value['from'] = 'Aaa' args.variables['VariableStringRange'].value['to'] = 'Zzz'
|
To change the value of a List variable, you need to access the list value by its index. You can also set the values of the entire list at once by using a prepared array, for example
app.py |
from stimulsoft_reports.events import StiVariablesEventArgs
def prepareVariables(args: StiVariablesEventArgs): args.variables['VariableStringList'].value[0] = 'Test' args.variables['VariableIntList'].value = [1, 22, 333]
|
It is also permissible to create a new report variable if needed. To create a new variable not defined in the report, you must add a new StiVariable object to the variables dictionary using the new variable name. After that, the variable can be used for generating the report, meaning the variable will not be saved in the report template.
app.py |
from stimulsoft_reports.report import StiVariable from stimulsoft_reports.report.enums import StiVariableType
def prepareVariables(args: StiVariablesEventArgs): args.variables['NewVarInt'] = StiVariable('NewVarInt', StiVariableType.INT, 10)
|
After processing the onPrepareVariables event, a new collection will be sent to the client, containing only those variables whose values have been changed, as well as any new variables.
Information |
If a variable is used in an SQL query as an expression, i.e., enclosed in braces, such as {VariableName}, its value will not be automatically escaped. You need to ensure the security of these values yourself or use the variable as a query parameter, such as @VariableName. A detailed description of parameter you can found in the Connecting SQL Data Adapters section.
|
Report variables passed in URL query
The report generator can automatically assign values to variables passed in the URL query. To enable this, set the passQueryParametersToReport property to True in the event handler:
app.py |
@app.route('/report', methods = ['GET', 'POST']) def report(): report = StiReport() report.handler.passQueryParametersToReport = True if report.processRequest(request): return report.getFrameworkResponse()
|
All other actions the report generator will handle automatically. If a variable is present in the report, its value will be updated with the value from the URL query. If the variable does not exist in the report, it will be created for the report generation, meaning that the new variable will not be saved in the report template. Variable names passed in the URL query are case-insensitive.
Information |
All variable values will be assigned before the onPrepareVariables event is triggered, allowing you to further control and adjust the assigned values if necessary during this event.
|