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.