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

 

 

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

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

 

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

}

 

 

 

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

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

 

index.php

 

<?php

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

$report->onPrepareVariables = 'onPrepareVariables';

$report->renderHtml();

?>

 

function onPrepareVariables(args) {

var variables = args.variables;

}

 

 

 

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

 

Коллекция переменных представляет собой массив из объектов, содержащих имя переменной, ее тип и значение, например:

 

index.php

 

args.variables = [

{

name: "VariableString",

type: "String",

value: "Text value"

},

{

name: "VariableInt",

type: "Int32",

value: 20

}

];

 

 

 

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

 

Для доступа к значениям переменных отчета на стороне PHP сервера, необходимо на стороне клиента добавить вызов обработчика событий, а на стороне сервера определить одноименное событие onPrepareVariables в файле обработчика событий. Подробное описание работы событий находится в разделе Обработчик событий PHP.

 

index.php

 

<?php

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

$report->onPrepareVariables = true;

$report->renderHtml();

?>

 

 

 

В аргументах события будет передана коллекция переменных отчета, которая представляет собой ассоциативный массив, в котором в качестве ключа выступает имя переменной, а в качестве значения - объект, содержащий тип переменной и ее значение, например:

 

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();

};

 

 

 

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

 

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

 

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

 

 

 

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

 

handler.php

 

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

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

 

 

 

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

 

handler.php

 

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

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

 

 

 

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

 

handler.php

 

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

 

 

Информация

 

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

 

 

 

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

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

 

index.php

 

<?php

$handler = new \Stimulsoft\StiHandler();

$handler->passQueryParametersToReport = true;

$handler->renderHtml();

?>

 

 

 

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

 

Информация

 

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