Примеры

 

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

 

 

 

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

 

 

Событие загрузки данных

Для работы с SQL источниками данных, необходимо определить событие onBeginProcessData у объекта отчета, либо компонента вьювера или дизайнера. Событие будет вызвано при построении отчета, как только появится необходимость в подключении к используемым SQL источникам данных. В аргументах события будут переданы все необходимые параметры подключения к SQL источнику данных, а также параметры SQL запроса. Подробное описание работы событий находится в разделе Обработчик событий PHP.

 

index.php

 

<?php

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

$report->onBeginProceddData = true;

$report->renderHtml;

?>

 

 

 

При необходимости обработки параметров, передаваемых на сторону сервера перед их передачей, предусмотрена возможность определить JavaScript функцию для события:

 

index.php

 

<?php

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

$report->onBeginProceddData = 'onBeginProcessData';

$report->renderHtml;

?>

 

function onBeginProcessData(args) {

 

}

 

 

 

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

 

index.php

 

<?php

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

$report->onBeginProcessData = 'onBeginProcessData';

$report->renderHtml();

?>

 

function onBeginProcessData(args) {

var connectionString = args.connectionString;

var queryString = args.queryString;

}

 

 

 

Подробное описание доступных значений аргументов находится в разделе События генератора отчетов.

 

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

 

index.php

 

<?php

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

$report->onBeginProcessData = 'onBeginProcessData';

$report->renderHtml();

?>

 

function onBeginProcessData(args) {

// Change the connection string

if (args.connection == "MyConnectionName")

args.connectionString = "Server=localhost;Database=test;uid=root;password=******;";

 

// Change the SQL query

if (args.dataSource == "MyDataSource")

args.queryString = "SELECT * FROM MyTable";

}

 

 

 

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

 

index.php

 

args.parameters = [

{

name: "ParameterString",

type: 752,

typeName: "Text",

value: "Text value"

},

{

name: "ParameterInt",

type: 3,

typeName: "Int32",

value: 20

}

];

 

 

 

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

 

index.php

 

<?php

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

$report->onBeginProcessData = 'onBeginProcessData';

$report->renderHtml();

?>

 

function onBeginProcessData(args) {

// Change the SQL query parameters with the required values

if (args.parameters)

args.parameters["Parameter1"] = "TableName";

}

 

 

Информация

 

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

 

 

 

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

 

handler.php

 

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

// Change the connection string

if ($args->connection == "MyConnectionName")

$args->connectionString = "Server=localhost;Database=test;uid=root;password=******;";

 

// Change the SQL query

if ($args->dataSource == "MyDataSource")

$args->queryString = "SELECT * FROM MyTable";

 

return \Stimulsoft\StiResult::success();

};

 

 

 

Таким образом, в событии onBeginProcessData можно узнать тип базы данных, имя подключения и имя источника данных, а также узнать и при необходимости скорректировать строку подключения и SQL запрос на получение данных. Измененные значения не будут переданы на сторону клиента, поэтому в данном событии на стороне PHP сервера можно использовать конфиденциальные данные, такие как логин и пароль в строке подключения, имена и префиксы таблиц и т.п.

 

Также в данном событии можно задать значения параметров запроса SQL источника данных. Подробнее о параметрах SQL запроса рассмотрено в этом разделе в главе Использование параметров в SQL запросе.

 

 

Событие подключения данных

Для просмотра либо корректировки загруженных данные перед их подключением и построением отчета, необходимо определить JavaScript событие onEndProcessData у объекта отчета, либо компонента вьювера или дизайнера:

 

index.php

 

<?php

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

$report->onEndProcessData = 'onEndProcessData';

$report->renderHtml();

?>

 

function onEndProcessData(args) {

var result = args.result;

}

 

 

 

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

 

Объект данных выполненного SQL запроса имеет следующую структуру:

 

index.php

 

args.result = {

count: 3,

columns: ["id", "username", "phone"],

types: ["int", "string", "string"],

rows: [

length: 2,

["1", "Mario Pontes", "555-6874"],

["2", "Helen Bennett", "555-2376"]

]

}

 

 

 

Доступные свойства объекта данных указаны в таблице:

 

Наименование

Описание

count

Общее количество колонок таблицы SQL источника данных.

columns

Имена колонок таблицы SQL источника данных.

types

Типы колонок таблицы SQL источника данных, приведенные к известным типам для генератора отчетов.

rows

Строки данных SQL источника данных, представляет собой массив из массивов всех строк таблицы.

 

 

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

 

Для просмотра либо корректировки загруженных данных на стороне PHP сервера перед их отправкой на сторону JavaScript клиента, необходимо определить событие onEndProcessData в файле обработчика событий:

 

handler.php

 

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

$result = $args->result;

 

return \Stimulsoft\StiResult::success();

};

 

 

 

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

 

Объект данных выполненного SQL запроса имеет следующую структуру:

 

handler.php

 

$args->result->count = 3;

$args->result->columns = array("id", "username", "phone");

$args->result->types = array("int", "string", "string");

$args->result->rows = array(

array("1", "Mario Pontes", "555-6874"),

array("2", "Helen Bennett", "555-2376")

);

 

 

 

Доступные свойства объекта данных указаны в таблице:

 

Наименование

Описание

count

Общее количество колонок таблицы SQL источника данных.

columns

Имена колонок таблицы SQL источника данных.

types

Типы колонок таблицы SQL источника данных, приведенные к известным типам для генератора отчетов.

rows

Строки данных SQL источника данных, представляет собой массив из массивов всех строк таблицы.

 

 

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

 

 

Использование параметров в SQL запросе

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

 

SQL Data Source

 

SELECT * FROM @Parameter1 WHERE UserID = @Parameter2

 

 

 

Все значения параметров будут переданы на сторону PHP сервера в виде отдельной коллекции, и могут быть проверены и изменены перед выполнением SQL запроса. Для доступа к значением параметров, необходимо воспользоваться коллекцией $args->parameters в событии onBeginProcessData, например:

 

handler.php

 

$args->parameters['Parameter1']->value = 'TableName';

$args->parameters['Parameter2']->value = 10;

 

 

Информация

 

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

 

 

 

Если в отчете используется несколько источников данных, необходимо выполнять проверку перед присвоением параметров. В противном случае, возникнет ошибка выполнения PHP скрипта, если какой-либо из параметров будет отсутствовать в текущем источнике данных. Например, в отчете создано два источника данных, оба имеют один общий параметр, и один параметр только во втором источнике данных:

 

handler.php

 

$args->parameters['Parameter1']->value = 'TableName';

 

if ($args->dataSource == 'DataSource2')

$args->parameters['Parameter2']->value = 10;

 

 

 

Использование переменной отчета в качестве SQL параметра

Предусмотрена возможность использования переменной в качестве SQL параметра. Для этого в редакторе переменной отчета достаточно установить свойство Allow using as SQL parameter, после чего её можно использовать в любом SQL запросе. Синтаксис будет точно таким же, как и при использовании параметров в источнике данных.

 

Информация

 

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

 

 

 

Экранирование значений параметров

Все значения параметров будут автоматически экранированы для исключения возможности SQL инъекций и нарушения безопасности выполнения запросов. Если вам не требуется экранирование, и вы сами контролируете безопасность значений параметров, автоматическое экранирование можно отключить. Для этого достаточно установить свойство $escapeQueryParameters в значение false у обработчика событий:

 

index.php

 

<?php

$handler = new \Stimulsoft\StiHandler();

$handler->escapeQueryParameters = false;

$handler->renderHtml();

?>

 

 

 

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

 

Информация

 

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