Подключение SQL адаптеров данных
Примеры |
Полный код примера можно найти на 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}, то экранирование применяться не будет в любом случае. Подробное описание работы переменных находится в разделе Работа с переменными отчета.
|