Генератор отчетов позволяет использовать переменные в выражениях, запросах, фильтрах и других элементах отчета. Предусмотрена возможность предварительного просмотра и изменения значений переменных из кода перед построением отчета.

 

 

Доступ к значениям переменных из кода

Генератор отчетов позволяет легко получить прямой доступ к переменным в шаблоне отчета через словарь данных. Для этого достаточно определить событие onBeforeRender у объекта отчета, в аргументах которого на стороне JavaScript клиента будет передан объект отчета. Подробное описание доступных значений свойств, передаваемых в аргументах события, находится в разделе События генератора отчетов.

 

Для доступа к переменной отчета, необходимо использовать JavaScript функцию getByName() у коллекции переменных в словаре данных отчета. Для изменения значения переменной, достаточно присвоить его в свойстве value, при этом нет необходимости проверять установленный тип переменной - преобразование типов будет выполнено автоматически.

 

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

 

index.php

 

<?php

use Stimulsoft\Report\StiReport;

 

$report = new StiReport();

$report->onBeforeRender = 'beforeRender';

$report->loadFile('reports/Variables.mrt');

$report->render();

?>

 

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

 

 

 

Прямой доступ к переменным в шаблоне отчета на стороне PHP сервера не предусмотрен.

 

Информация

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

 

 

 

Событие подготовки значений переменных

Генератор отчетов позволяет легко получить доступ к переменным перед построением отчета. Для этого достаточно определить событие onPrepareVariables у объекта отчета. В аргументах события будет передана коллекция переменных отчета с их типами и значениями. Если переменная инициализируется как выражение, то в коллекцию будет передано уже подсчитанное значение выражения. Подробное описание доступных значений свойств, передаваемых в аргументах события, находится в разделе События генератора отчетов.

 

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

 

index.php

 

<script>

function prepareVariables(args) {    

args.variables = [

{

name: "VariableString",

type: "String",

value: "Text value"

},

{

name: "VariableInt",

type: "Int32",

value: 20

}

    ]};

</script>

 

 

 

Пример изменения значения переменной на стороне JavaScript клиента:

 

index.php

 

<?php

use Stimulsoft\Report\StiReport;

 

$report = new StiReport();

$report->onPrepareVariables = 'prepareVariables';

$report->loadFile('reports/Variables.mrt');

$report->render();

?>

 

...

 

<script>

function prepareVariables(args) {

let variables = args.variables;

 

variables.find(item => item.name == "VariableString").value = "Text value";

variables.find(item => item.name == "VariableInt").value = 20;

}

</script>

 

 

 

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

 

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

 

index.php

 

<?php

use Stimulsoft\Events\StiVariablesEventArgs;

use Stimulsoft\Report\StiReport;

 

$report = new StiReport();

$report->onPrepareVariables = function (StiVariablesEventArgs $args) {

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

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

};
$report->loadFile('reports/Variables.mrt');

$report->render();

?>

 

 

 

Полный код примера доступен на GitHub.

 

Для изменения значения простой переменной, достаточно заменить значение value в коллекции переменных. Значение должно быть того же типа, что и исходное. Переменные типа DateTime передаются в виде строкового значения в формате "YYYY-MM-dd HH-mm-ss".

 

index.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';

 

 

 

Для изменения значения переменной типа Range, необходимо использовать вложенные значения value->from и value->to выбранной переменной в коллекции. Формат каждого из двух значений такой же, как и у простой переменной:

 

index.php

 

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

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

 

 

 

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

 

index.php

 

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

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

 

 

 

Для создания новой переменной, не определенной в отчете, необходимо присвоить подготовленный ассоциативный массив в формате ['value' => 'New Value'] в коллекцию переменных, используя новое имя переменной. После этого переменную можно использовать для построения отчета, то есть в шаблоне отчета переменная сохранена не будет.

 

index.php

 

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

 

 

Информация

 

Если переменная используется в SQL запросе в виде выражения, т.е. записана в фигурных скобках, например {VariableName}, то ее значение не будет автоматически экранировано. Вам необходимо самим следить за безопасностью значений, либо использовать переменную как параметр запроса, например @VariableName. Подробное описание работы параметров находится в разделе Подключение SQL адаптеров данных.

 

 

 

Переменные отчета, передаваемые в URL запросе

Генератор отчетов имеет возможность автоматически присваивать значения переменных, переданных в URL запросе. Для этого необходимо установить свойство $passQueryParametersToReport в значение true у обработчика событий:

 

index.php

 

<?php

use Stimulsoft\Report\StiReport;

 

$report = new StiReport();        

$report->handler->passQueryParametersToReport = true;

$report->process();

?>

 

 

 

Все остальные действия генератор отчетов сделает автоматически. Если переменная присутствует в отчете, то ее значение будет изменено на значение из URL запроса. Если такой переменной в отчете нет - она будет создана для построения отчета, то есть в шаблоне отчета новая переменная сохранена не будет. Имена переменных, передаваемых в URL запросе, не чувствительны к регистру.

 

Информация

 

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