В новой версии 2024.4 мы анонсируем крупное обновление для наших Reports.PHP и Dashboards.PHP продуктов. Был проведён полный рефакторинг кода, улучшена работа событий компонентов, доработан обработчик запросов, добавлены настройки экспортирования, и, самое главное, добавлена возможность построения и экспортирования отчета на стороне сервера. Ниже описаны основные улучшения, и примеры их использования.
Построение и экспорт отчета на стороне сервера реализован максимально просто для использования. Для этого достаточно переключить свойство отчета engine в режим работы на сервере, и использовать уже существующие методы render() и exportDocument(). Теперь эти функции будут автоматически переключены в режим работы на сервере, все события отчета будут работать так же, как и в случае работы генератора отчетов на стороне сервера.
Пример построения отчета и получения файла документа (либо его сохранения в файл):
Все указанные проблемы можно легко решить, включив режим совместимости со старой версией. Мы рекомендуем данный вариант как временный, т.к. в этом случае могут неверно работать некоторые нововведения. Для включения режима совместимости необходимо добавить одну строку кода в начало файла.
Для решения проблемы с пространствами имен достаточно заменить старые пространства на новые, каких-либо других изменений в коде не требуется.
Первый вариант - перенаправить запросы на отдельный файл, в этом случае события будут работать так же, как и раньше. Для этого просто укажите путь к файлу обработки событий.
При использовании отдельного обработчика
Первый вариант - просто убрать в HTML шаблоне страницы тэги <script></script>, никаких дополнительных действий не требуется.
Старый вариант
Старый вариант
Примеры использования с последними версиями скриптов находятся по данной ссылке.
Минимальные требования повышены до PHP 7.0
В новой версии мы добавили ряд значительных улучшений и изменений, о которых расскажем ниже. В связи с этим возникла необходимость повысить минимальные требования до PHP 7.0, чтобы реализовать задуманный функционал наилучшим образом. PHP 5.6 является давно устаревшей версией, её поддержка завершена в декабре 2018 года, соответственно, переход на более свежую версию предлагает больше возможностей, более высокую скорость работы и улучшенную безопасность.Упрощенная настройка скриптов компонентов
Ранее для добавления скриптов компонентов нужно было создавать специальный StiJavaScript объект, настраивать его для конкретного компонента, и отдельно выводить на HTML странице в определенном месте. Теперь в этом нет необходимости, компоненты сами могут развернуть свои скрипты - для этого достаточно одной строки кода. При необходимости, можно изменить настройки скриптов в самом компоненте.<?php
$viewer = new StiViewer();
$viewer->javascript->usePacked = false;
?>
<!DOCTYPE html>
<html>
<head>
<?php $viewer->javascript->renderHtml(); ?>
</head>Новые способы отображения компонентов
Ранее для отображения HTML кода компонента был доступен только один способ - вызов метода renderHtml(), который выведет весь необходимый для работы компонента код в текущем месте страницы. В новой версии работа указанного метода расширена, а также добавлен новый метод printHtml() для всех компонентов. Данный метод выведет полностью подготовленную HTML страницу со всеми необходимыми скриптами и HTML кодом. Этот способ очень удобен, если нет необходимости в своем шаблоне страницы, и компонент вьювера либо дизайнера отображается целиком на всю страницу.<?php
$viewer = new StiViewer();
$viewer->process();
$viewer->printHtml();
?>
Обработчик событий встроен в компоненты
Ранее обработчик событий создавался и настраивался как отдельный объект StiHandler, со своими настойками и скриптами, и никак не был связан с компонентами (отчетом, вьювером, дизайнером). Теперь можно работать только с компонентами, они сами создадут, настроят и развернут код обработчика событий. Все свойства обработчика можно настроить в самом компоненте. Для обработки событий добавлен специальный метод process(), который обработает запрос, и при необходимости вернет ответ на сторону клиента. Никаких дополнительных действий для этого не требуется.<?php
$viewer = new StiViewer();
// $viewer->handler->encryptData = true;
$viewer->process();
?>Упрощенный доступ к опциям компонентов
Ранее для настройки компонентов вьювера и дизайнера отчетов, необходимо было создать отдельный объект опций, настроить его, и передать в конструктор компонента. Теперь такой необходимости нет, объект опций уже встроен в компонент, достаточно просто изменить нужные свойства прямо в самом компоненте.<?php
$viewer = new StiViewer();
$viewer->options->appearance->backgroundColor = 'black';
$viewer->options->appearance->theme = StiViewerTheme::Office2022BlackGreen;
$viewer->options->toolbar->displayMode = StiToolbarDisplayMode::Separated;
$viewer->options->toolbar->showFullScreenButton = false;
?>Улучшенная работа событий
Ранее обработка всех событий компонентов производилась в одном файле handler.php, это решение было не всегда удобно и имело ограничения с одноименными событиями разных компонентов. В новой версии каждый компонент имеет свой набор событий. Теперь события могут быть вызваны как на стороне PHP сервера, так и на стороне JavaScript клиента. Более того, добавлена возможность назначить одному событию несколько обработчиков разных типов. Допускается присвоение либо добавление к событию PHP функции, названия JavaScript функции из текущего шаблона страницы, а также JavaScript функции в виде блока кода.<?php
$viewer = new StiViewer();
$viewer->onBeginProcessData = function (StiDataEventArgs $args) {
if ($args->connection == 'MyConnectionName')
$args->connectionString = 'Server=localhost;Database=test;uid=root;password=******;';
};
$viewer->onBeginExportReport->append(function (StiExportEventArgs $args) {
$args->fileName = "MyExportedFileName.$args->fileExtension";
if ($args->format == StiExportFormat::Pdf) {
/** @var StiPdfExportSettings $settings */
$settings = $args->settings;
$settings->creatorString = 'My Company Name';
}
});
$viewer->onBeginExportReport->append('beginExportReport');
$viewer->onBeginExportReport->append('
if (args.format == Stimulsoft.Report.StiExportFormat.Pdf)
args.settings.imageResolution = 200;
');
$viewer->process();
?><?php
$viewer = new StiViewer();
$viewer->handler->url = 'handler.php';
?>Настройки экспортирования
В новой версии были добавлены настройки экспортирования для всех поддерживаемых форматов. Настройки можно передавать в функцию экспорта, также настройки будут переданы в события экспорта отчета.<?php
$report = new StiReport();
$settings = new StiPdfExportSettings();
$settings->creatorString = 'My Company Name';
$settings->keywordsString = 'SimpleList PHP Report Export';
$settings->embeddedFonts = false;
$report->exportDocument(StiExportFormat::Pdf, $settings);
?>
Построение и экспортирование отчета на стороне сервера
В новой версии мы добавили возможность построения и экспортирования отчета на стороне PHP сервера. Для этой цели используется универсальная платформа Node.js, работающая на различных операционных системах. Для работы с отчетом на стороне сервера необходимо иметь уже установленную платформу Node.js, либо воспользоваться специальными классами для ее установки и настройки.<?php
$nodejs = new StiNodeJs();
// Setting the path to the executable files of the already installed Node.js
//$nodejs->binDirectory = "C:\\Program Files\\nodejs";
//$nodejs->binDirectory = "/usr/bin/nodejs";
// Setting the path to the working directory where Node.js packages will be deployed
// By default, the current Python script execution directory is used
//$nodejs->workingDirectory = '';
// Installing the Node.js package from the official website, may take some time
// If the installation fails, the function will return false
$result = $nodejs->installNodeJS();
// Installing or updating product packages to the current version, may take some time
if ($result)
$result = $nodejs->updatePackages();
// Installation status or error text from Node.js engine
$message = $result ? 'The installation was successful.' : $nodejs->error;
?>Построение и экспорт отчета на стороне сервера реализован максимально просто для использования. Для этого достаточно переключить свойство отчета engine в режим работы на сервере, и использовать уже существующие методы render() и exportDocument(). Теперь эти функции будут автоматически переключены в режим работы на сервере, все события отчета будут работать так же, как и в случае работы генератора отчетов на стороне сервера.
Пример построения отчета и получения файла документа (либо его сохранения в файл):
<?php
$report = new StiReport();
$report->engine = StiEngineType::ServerNodeJS;
$result = $report->render();
if ($result) {
$document = $report->saveDocument();
// $result = $report->saveDocument('reports/SimpleList.mdc');
}
?><?php
$report = new StiReport();
$report->engine = StiEngineType::ServerNodeJS;
$result = $report->render();
if ($result) {
$result = $report->exportDocument(StiExportFormat::Text);
// $result = $report->exportDocument(StiExportFormat::Pdf, null, false, 'reports/SimpleList.pdf');
}
?>Режим обратной совместимости
Мы постарались реализовать все нововведения таким образом, чтобы уже существующие проекты были максимально работоспособны, а переход на новую версию был плавным. После обновления могут возникнуть следующие проблемы:- свойство или метод помечен как устаревший;
- не найдены некоторые классы и перечисления;
- запросы обработчика не направляются в файл handler.php;
- неверно выводится HTML код компонента.
Все указанные проблемы можно легко решить, включив режим совместимости со старой версией. Мы рекомендуем данный вариант как временный, т.к. в этом случае могут неверно работать некоторые нововведения. Для включения режима совместимости необходимо добавить одну строку кода в начало файла.
<?php
require_once 'vendor/autoload.php';
\Stimulsoft\StiHandler::enableLegacyMode();
?>Устаревшие свойства и методы
В новой версии некоторые свойства изменили свое расположение, а некоторые методы были переименованы для более четкого понимания и организации кода. Старые имена сохранены и помечены как @deprecated, для решения проблемы просто замените их на новые, указанные в описании устаревшего свойства либо метода.Пространства имен
В новой версии было добавлено значительное количество новых классов и перечислений, поэтому нам необходимо было пересмотреть пространства имен для исключения пересечений. Ниже представлена таблица соответствий пространств имен.| Старые пространства имен | Новые пространства имен |
|---|---|
| Stimulsoft\StiComponentType | Stimulsoft\Enums\StiComponentType |
| Stimulsoft\StiEventType | Stimulsoft\Enums\StiEventType |
| Stimulsoft\StiExportFormat | Stimulsoft\Export\Enums\StiExportFormat |
| Stimulsoft\StiExportAction | Stimulsoft\Viewer\Enums\StiExportAction |
| Stimulsoft\StiPrintAction | Stimulsoft\Viewer\Enums\StiPrintAction |
| Stimulsoft\Report\(enum classes) | Stimulsoft\Report\Enums\(enum classes) |
| Stimulsoft\Viewer\(enum classes) | Stimulsoft\Viewer\Enums\(enum classes) |
| Stimulsoft\Designer\(enum classes) | Stimulsoft\Designer\Enums\(enum classes) |
| Stimulsoft\(event classes) | Stimulsoft\Events\(event classes) |
Для решения проблемы с пространствами имен достаточно заменить старые пространства на новые, каких-либо других изменений в коде не требуется.
Запросы обработчика событий
В новой версии все события и сам обработчик событий были перенесены в компоненты, поэтому по умолчанию все запросы теперь приходят на текущую страницу с компонентом, вместо отдельного файла handler.php обработки событий. Есть несколько вариантов решения данной проблемы.Первый вариант - перенаправить запросы на отдельный файл, в этом случае события будут работать так же, как и раньше. Для этого просто укажите путь к файлу обработки событий.
При использовании отдельного обработчика
<?php
$handler = StiHandler("handler.php");
?><?php
$viewer = new StiViewer();
$viewer->handler->url = "handler.php";
?><?php
$viewer = new StiViewer();
$viewer->onBeginProcessData = function (StiDataEventArgs $args) {
if ($args->connection == 'MyConnectionName')
$args->connectionString = 'Server=localhost;Database=test;uid=root;password=******;';
};
$viewer->process();
?>Вывод HTML кода компонентов
В новой версии добавлены новые варианты вывода HTML кода компонентов, поэтому поведение по умолчанию уже существующих методов было скорректировано. Главным изменением является то, что метод renderHtml() теперь помимо основного кода компонента, выводит HTML тэги <script></script>, это может нарушить работу уже существующих проектов. Есть несколько вариантов решения данной проблемы.Первый вариант - просто убрать в HTML шаблоне страницы тэги <script></script>, никаких дополнительных действий не требуется.
Старый вариант
<script>
<?php
$viewer = new StiViewer();
$viewer->renderHtml();
?>
</script>
<?php
$viewer = new StiViewer();
$viewer->renderHtml();
?>Старый вариант
<?php
$viewer = new StiViewer();
?>
<script>
function showViewer() {
<?php $viewer->renderHtml(); ?>
}
</script>
<?php
$viewer = new StiViewer();
?>
<script>
function showViewer() {
<?php echo $viewer->getHtml(StiHtmlMode::Scripts); ?>
}
</script>
Уже доступно для использования
Все указанные нововведения уже доступны для использования, начиная с версии 2024.3.2, и в данный момент находятся на стадии тестирования и финальных доработок. Вы можете загрузить скрипты из отдельной ветки репозитория, которая вскоре будет выгружена в основную. Подготовлены новые примеры использования, а документация в ближайшее время будет обновлена. Мы рады любым комментариям и пожеланиям по доработке продукта.Примеры использования с последними версиями скриптов находятся по данной ссылке.