Запуск отчетов

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

Figure 1. Запуск отчета

Запуск из списка отчетов

Самый простой способ запустить отчеты - из экрана Run report. Пользователь должен иметь разрешение на доступ к этому экрану. Список будет содержать все отчеты, доступные пользователю в соответствии с его ролью. Если отчет имеет внешние параметры, они будут запрошены в специальной форме при запуске отчета.

Запуск из экранов

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

Типы действий и примеры их использования описаны ниже.

RunReportAction

io.jmix.reportsflowui.action.RunReportAction - это стандартное действие для запуска отчетов, связанных с текущим экраном или компонентом списка. Оно должно быть определено для Button или компонента списка (dataGrid, treeDataGrid).

Ниже приведен пример использования декларативного действия для DataGrid:

<hbox id="buttonsPanel" classNames="buttons-panel">
    <!-- ...  -->
    <button id="runBtn" action="booksDataGrid.run"/> (1)
</hbox>
<dataGrid id="booksDataGrid"
          width="100%"
          minHeight="20em"
          dataContainer="booksDc">
    <actions>
        <!-- ...  -->
        <action id="run" type="report_runReport"/> (2)
    </actions>
</dataGrid>

1	Добавляет кнопку с действием запуска отчета.
2	Атрибут `type` определяет конкретный тип действия `report_runReport`, предоставляемый дополнением Reports.

Пример программного создания действия вместе с кнопкой, объявленной в XML-дескрипторе экрана:

@ViewComponent
private JmixButton runBtn;

@Autowired
private Actions actions;

@Subscribe
public void onInit(final InitEvent event) {
    RunReportAction<Book> action = actions.create(RunReportAction.ID);

    runBtn.setAction(action);
}

При выполнении действия появится модальное диалоговое окно Run report, в котором отобразятся отчеты, связанные с текущим экраном. Когда пользователь выберет отчет из списка, отобразится форма ввода параметров (если они были определены), и отчет будет сгенерирован.

RunListEntityReportAction

io.jmix.reportsflowui.action.RunListEntityReportAction - это стандартное действие для печати отчетов для экземпляров сущностей, связанных с компонентом списка (dataGrid, treeDataGrid).

Действие выбирает только отчеты, имеющие внешний параметр типа Entity или List of entities, где тип сущности параметра совпадает с типом сущности, отображаемой компонентом списка. Если в результате выбора доступен только один отчет, он вызывается немедленно. Если доступно несколько отчетов, их список предлагается пользователю для выбора.

Значение внешнего параметра передается в отчет по следующим правилам:

Если параметр имеет тип List of entities, в него передается список экземпляров, выбранных в данный момент в компоненте списка.
Если параметр имеет тип Entity, и в компоненте списка выбран один экземпляр (выделена одна строка), то этот экземпляр передается в отчет.
Если параметр имеет тип Entity, и в компоненте списка выбрано несколько строк, то отчет запускается несколько раз в соответствии с количеством выбранных экземпляров. После выполнения пользователь получает один ZIP-архив, содержащий все сгенерированные отчеты.

Ниже приведен пример использования декларативного действия для DataGrid:

<hbox id="buttonsPanel" classNames="buttons-panel">
    <!-- ...  -->
    <button id="runListBtn" action="authorsDataGrid.runList"/> (1)
</hbox>
<dataGrid id="authorsDataGrid"
          width="100%"
          minHeight="20em"
          dataContainer="authorsDc">
    <actions>
        <!-- ...  -->
        <action id="runList" type="report_runListEntityReport"/> (2)
    </actions>
</dataGrid>

1	Добавляет кнопку с действием запуска отчета для списка сущностей.
2	Атрибут `type` определяет конкретный тип действия `report_runListEntityReport`, предоставляемый фреймворком.

Пример программного создания действия вместе с кнопкой, объявленной в XML-дескрипторе экрана:

@ViewComponent
private JmixButton runListBtn;

@Autowired
private Actions actions;

@Subscribe
public void onInit(final InitEvent event) {
    RunListEntityReportAction<Author> action = actions.create(RunListEntityReportAction.ID);

    runListBtn.setAction(action);
}

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

run list entity report action confirmation

После этого откроется модальное диалоговое окно Run report, в котором будут отображены отчеты, связанные с текущим экраном. Из этого модального окна пользователь может запустить какой-либо отчет для выбранной сущности.

RunSingleEntityReportAction

io.jmix.reportsflowui.action.RunSingleEntityReportAction - это действие, связанное с экраном деталей сущности. Действие выбирает только отчеты, имеющие внешний параметр типа Entity или List of entities, где тип сущности параметра совпадает с типом редактируемой сущности. Если в результате выбора доступен только один отчет, он вызывается немедленно. Если доступно несколько отчетов, их список предлагается пользователю для выбора.

Значение внешнего параметра - экземпляр редактируемой сущности - передается в отчет. Если параметр имеет тип List of entities, то передается список, содержащий один элемент.

Ниже приведен пример использования действия в кнопке, расположенной рядом со стандартными кнопками OK и Cancel:

<hbox id="detailActions">
    <button id="saveAndCloseBtn" action="saveAction"/>
    <button id="closeBtn" action="closeAction"/>
    <button id="reportButton" icon="PRINT"/>
</hbox>

@Autowired
private Actions actions;

@ViewComponent
private JmixButton reportButton;

@Subscribe
public void onInitEntity(final InitEntityEvent<Book> event) {
    RunSingleEntityReportAction<Book> action = actions.create(RunSingleEntityReportAction.ID);
    action.setReportOutputName(null);

    reportButton.setAction(action);
}

API отчетов

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

ReportRunner

ReportRunner - это интерфейс, используемый для запуска отчетов. Все его методы возвращают объект ReportOutputDocument, который содержит результат выполнения отчета.

Ниже приведено несколько примеров использования ReportRunner.

Запуск отчета на основе информации, указанной в объекте ReportRunContext:

@Autowired
private ReportRunner reportRunner;

@Subscribe("rrcBtn2")
public void onRrcBtn2Click(ClickEvent<JmixButton> event) {
    ReportOutputDocument document = reportRunner
            .run(new ReportRunContext(report).setParams(paramsMap)); (1)
}

1	`ReportRunContext` содержит сущность отчета и параметры.

Запуск отчета по его коду и дополнительной информации, указанной с использованием интерфейса fluent:

@Autowired
private ReportRunner reportRunner;

@Subscribe("rrBtn1")
public void onRrBtn1Click(ClickEvent<JmixButton> event) {
    ReportOutputDocument document = reportRunner.byReportCode("BOOKS") (1)
            .addParam("type", type) (2)
            .withTemplateCode("books-template") (3)
            .run(); (4)
}

1	Точка входа в fluent-интерфейс для отчета с указанным кодом.
2	Добавляет входной параметр в карту параметров.
3	Устанавливает код шаблона, который будет использоваться для запуска отчета.
4	Создает экземпляр `ReportRunContext` и запускает отчет, используя этот контекст запуска.

Запуск отчета по сущности отчета и дополнительной информации, указанной с использованием интерфейса fluent:

@Autowired
private ReportRunner reportRunner;

@Subscribe("rrBtn2")
public void onRrBtn2Click(ClickEvent<JmixButton> event) {
    ReportOutputDocument document = reportRunner.byReportEntity(report)
            .addParam("type", type)
            .withOutputType(ReportOutputType.PDF) (1)
            .withOutputNamePattern("Books") (2)
            .run();
}

1	Устанавливает тип выходного документа.
2	Устанавливает шаблон имени выходного документа.

Вы можете получить содержимое отчета и имя файла непосредственно из ReportOutputDocument:

String documentName = document.getDocumentName();

byte[] content = document.getContent();

UIReportRunner

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

Отображение результата выполнения отчета в браузере (в случае табличных шаблонов).
```
uiReportRunner.runAndShow(new UiReportRunContext(report));
```
Показывать ли диалог для ввода параметров отчета перед запуском. Используйте для этого ParametersDialogShowMode. Поддерживаются три режима:
- YES - показывать диалог для ввода параметров отчета.
- NO - не показывать диалог для ввода параметров отчета.
- IF_REQUIRED - показывать диалог для ввода параметров отчета, если:
  - Отчет имеет входные параметры;
  - Отчет имеет несколько шаблонов;
  - Отчет имеет один шаблон с изменяемым типом вывода.

Выполнять генерацию отчета синхронно или в фоновом режиме:

uiReportRunner.byReportEntity(report)
        .withParametersDialogShowMode(ParametersDialogShowMode.IF_REQUIRED)
        .inBackground(RunReportView.this)
        .runAndShow();

Запустить отчет несколько раз для указанного псевдонима параметра и значений:
```
uiReportRunner.byReportEntity(report)
        .withOutputType(ReportOutputType.PDF)
        .withTemplateCode("publication-template")
        .withParametersDialogShowMode(ParametersDialogShowMode.NO)
        .runMultipleReports("entity", publicationList);
```
Метод runMultipleReports() запускает отчет для каждого объекта из указанной коллекции. Объекты в коллекции должны иметь тот же тип, что и входной параметр с указанным псевдонимом.

ReportRunContext

Класс ReportRunContext хранит следующую информацию, необходимую для запуска отчета:

Сущность Report;
Сущность ReportTemplate: если не указана, используется шаблон по умолчанию;
Входные параметры;
Тип выходного документа;
Шаблон имени выходного документа.

Рассмотрим примеры создания ReportRunContext:

ReportRunContext context = new ReportRunContext(report)
        .addParam("type", type)
        .setOutputNamePattern("Books");

ReportRunContext context = new ReportRunContext(report)
        .setReportTemplate(template)
        .setOutputType(ReportOutputType.PDF)
        .setParams(paramsMap);

ReportZipUtils

Интерфейс ReportZipUtils помогает упаковать список объектов ReportOutputDocument в один ZIP-архив.

byte[] zipArchiveContent = reportZipUtils.createZipArchive(documents);
downloader.download(zipArchiveContent, "Reports.zip", DownloadFormat.ZIP);