The report generator allows you to use variables in expressions, requests, filters and other report elements. There is an ability, which allows you preview and change values of variables from a code before you render a report.

 

 

Access to values of variables from a code

The report generator allows you easily to get access to report variables via the data dictionary. To do it you should use the getByName() function for the collection of variables. To change values of a variable you should assign it in the value property and you don't need to check the set type of a variable and the conversion of types will be done automatically. For example you need to change string and integer value of specified variables.

 

index.php

 

<?php

$report = new \Stimulsoft\Report\StiReport();

$report->onBeforeRender = 'onBeforeRender';

$report->renderHtml();

?>

 

function onBeforeRender(args) {

var report = args.report;

 

var variableString = report.dictionary.variables.getByName("VariableString");

variableString.value = "Text value";

 

var variableInt = report.dictionary.variables.getByName("VariableInt");

variableInt.value = "20";

}

 

 

 

The event of preparing values of variables

To get access to values of variables before designing a report, you should define the onPrepareVariables event for a report object or the viewer or the designer component.

 

index.php

 

<?php

$report = new \Stimulsoft\Report\StiReport();

$report->onPrepareVariables = 'onPrepareVariables';

$report->renderHtml();

?>

 

function onPrepareVariables(args) {

var variables = args.variables;

}

 

 

 

In arguments of the event, the collection of report variables with their values will be transferred. If a variable is initialized as an expression, a calculated value of the expression will be transferred to the collection. You can find a detailed description of values of arguments in the Engine Events chapter.

 

The collection of variables is an array of objects, which contain the name of a variable, its type and value. For example.

 

index.php

 

args.variables = [

{

name: "VariableString",

type: "String",

value: "Text value"

},

{

name: "VariableInt",

type: "Int32",

value: 20

}

];

 

 

 

You can change values of variables and the type of a new value should correspond to the type of a changed variable.

 

To get access to values of report values on the PHP server-side you should add the invoke of event handler on the client-side, and define the onPrepareVariables event with the same name in the file of event handler. You can find a detailed description of work of events in the PHP events handler chapter.

 

index.php

 

<?php

$report-> = new \Stimulsoft\Report\StiReport();

$report->onPrepareVariables = true;

$report->renderHtml();

?>

 

 

 

In arguments of the event the collection of report variables, which is an associative array where the name of a variable is a key and the object, which contains the type of a variable and its value. For example.

 

handler.php

 

$handler->onPrepareVariables = function ($args) {

$args->variables['VariableString']->value = 'Text value from Server-Side';

 

$args->variables['VariableInt']->value = 123;

$type = $args->variables['VariableInt']->type; // 'Int32'

 

return \Stimulsoft\StiResult::success();

};

 

 

 

You can change values of variables and the type of a new value should correspond to the type of a changed variable. Also, you can create a new report variable, if needed. A new collection, which contains only the variables with changed values and new variables will be transferred to the client-side.

 

To change the value of a simple variable you should change a value in the collection of variables. A value should be of the same type as an original. The values of the DataTime type are transferred as a string value in the "YYYY-MM-dd HH-mm-ss": format.

 

handler.php

 

$args->variables['VariableString']->value = 'Value from Server-Side';

$args->variables['VariableInt']->value = 123;

$args->variables['VariableDecimal']->value = 123.456;

$args->variables['VariableDateTime']->value = '2021-03-20 22:00:00';

 

 

 

To change a value of the Range type variable, you should use the nested value->from and value->to values of the variable you select in the collection. The format of each of two values is similar to a simple variable.

 

handler.php

 

$args->variables['VariableStringRange']->value->from = 'Aaa';

$args->variables['VariableStringRange']->value->to = 'Zzz';

 

 

 

To change the values of the List type variable, you should use a value from the list by its index. You can set values of all the list as a prepared array.

 

handler.php

 

$args->variables['VariableStringList']->value[0] = 'Test';

$args->variables['VariableStringList']->value = ['1', '2', '2'];

 

 

 

To create a new variable, which is not defined in a report you should assign a prepared associative array in the ['value' => 'New Value'] format to the collection of variables using a new variable's name. After, you can use the variable to render a report, it means the variable will not be saved in the report template.

 

handler.php

 

$args->variables['NewVariable'] = ['value' => 'New Value'];

 

 

Information

 

If a variable is used in a SQL query as an expression, i.e. it is typed in braces, for example the {VariableName} , its value will not be automatically escaped. You should keep an eye on the safety of values or use a variable as parameter of query, for example @VariableName. You can find a detailed description of work of parameters in the Connecting SQL data adapters chapter.

 

 

 

Report variables transferred in a URL query

The report generator has an ability, which allows you automatically to assign values of variables, transferred in the URL query. To do this, set the $passQueryParametersToReport property of the event handler to true:

 

index.php

 

<?php

$handler = new \Stimulsoft\StiHandler();

$handler->passQueryParametersToReport = true;

$handler->renderHtml();

?>

 

 

 

The report generator will make all other actions automatically. If there is a variable in a report, its value will be changed to a value from the URL query. If there is no such variable in a report, it will be created to render the report. It means, a new variable will not be saved in the report template. The names of variables, transferred in the URL query are not case sensitive.

 

Information

 

All values of variables will be assigned before the onPrepareVariables event invoked. This way in this event, you can additionally control the set values and correct them, if needed.