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

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

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

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

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

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

io.jmix.reportsui.action.list.RunReportAction` – стандартное действие, которое отображает список всех доступных отчетов. Оно должно быть определено для Button или компонента-списка (Table, DataGrid и т.д.).

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

<actions>
    <action id="run" type="runReport"/> (1)
</actions>
    <button id="runBtn" action="booksTable.run"/> (2)
</buttonsPanel>

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

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

@Autowired
private Button runReportBtn;

@Autowired
private Actions actions;

@Subscribe
public void onInit(InitEvent event) {
    RunReportAction action = actions.create(RunReportAction.class, "runReport");

    runReportBtn.setAction(action);
}

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

io.jmix.reportsui.action.list.ListPrintFormAction – a standard action for printing reports for entity instances associated with a list component (Table, DataGrid, etc.).

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

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

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

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

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

<actions>
    <action id="list" type="listPrintForm"/> (1)
</actions>
<buttonsPanel id="buttonsPanel"
              alwaysVisible="true">
    <button id="listBtn" action="authorsTable.list"/> (2)
</buttonsPanel>

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

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

@Autowired
private Button listPrintFormBtn;

@Autowired
private Actions actions;

@Subscribe
public void onInit(InitEvent event) {
    ListPrintFormAction action = actions.create(ListPrintFormAction.class, "listPrintForm");
    listPrintFormBtn.setAction(action);
}

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

Figure 1. Окно подтверждения

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

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

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

Ниже приведен пример использования действия в кнопке, расположенной рядом со стандартными кнопками OK и Cancel:
- XML-дескриптор
  
  <hbox id="editActions" spacing="true"> <button id="reportButton" icon="PRINT"/> </hbox>
- Контроллер
  
  @Inject private Button reportButton; @Autowired private Actions actions; @Subscribe public void onInit(InitEvent event) { EditorPrintFormAction action = actions.create(EditorPrintFormAction.class); action.setEditor(this); action.setReportOutputName(null); reportButton.setAction(action); }

Reports API

ReportRunner

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

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

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

@Autowired
protected ReportRunner reportRunner;

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

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

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

@Autowired
protected ReportRunner reportRunner;

@Subscribe("rrBtn1")
protected void onRrBtn1Click(Button.ClickEvent 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
protected ReportRunner reportRunner;

@Subscribe("rrBtn2")
protected void onRrBtn2Click(Button.ClickEvent 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(RunReportScreen.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);