Reports: Render XLS/XLSX and ODS Output in Vaadin Spreadsheet jmix-framework/jmix#5138

[KremnevDmitry]

See: #5138

Reports Spreadsheet

The Reports Spreadsheet add-on enables in-browser rendering of XLS/XLSX report output via the Vaadin Spreadsheet component. Instead of downloading the generated report file, users can open it in a dialog with a fully-functional spreadsheet viewer, review the data, optionally edit cells, and download the modified workbook.

The add-on is a premium module available for Jmix applications.

Getting Started

Add the runtime dependency to your project:

implementation 'io.jmix.reports:jmix-reports-spreadsheet-flowui-starter'

The add-on auto-activates only when all of the following are present on the classpath: jmix-reports-flowui, the Vaadin Spreadsheet add-on (io.jmix.spreadsheet:jmix-spreadsheet-starter), and the Vaadin Spreadsheet component itself.

Once enabled, the existing Reports views (Reports list, Run report, Execution history) automatically expose new actions — Open in Spreadsheet next to the standard Run/Download actions.

Basic concepts

Report Execution Presentation

A Report Execution Presentation is a strategy that defines how a particular output channel selects templates, output types, and decides whether a parameters dialog is required. Each presentation has a stable identifier registered in ReportExecutionPresentationIds:

ReportExecutionPresentationIds.DEFAULT      // standard download
ReportExecutionPresentationIds.TABLE        // in-dialog table viewer
ReportExecutionPresentationIds.SPREADSHEET  // spreadsheet viewer (provided by this add-on)

The OSS reports-flowui module ships DefaultReportExecutionPresentation and TableReportExecutionPresentation. The premium add-on contributes SpreadsheetReportExecutionPresentation, which restricts template and output choices to combinations renderable by the Vaadin Spreadsheet (currently XLS/XLSX).

To register a custom presentation, implement ReportExecutionPresentation and expose it as a Spring bean:

@Component
public class MyCustomPresentation implements ReportExecutionPresentation {

    @Override
    public String getId() {
        return "my-channel";
    }

    @Override
    public boolean supportsReport(@Nullable Report report) {
        // ...
    }

    // other strategy methods
}

---

Report Result Handler

A Report Result Handler receives the generated ReportOutputDocument after the runner finishes execution and decides what to do with it. Handlers form an ordered chain — each is called until one returns true:

public interface ReportResultHandler {
    boolean handle(ReportOutputDocument document, UiReportRunContext context);
}

Built-in handlers:

• TableReportResultHandler — opens table-output reports in ReportTableView.
• SpreadsheetInlineReportResultHandler (premium) — opens XLS/XLSX output in ReportSpreadsheetView when the run context targets the SPREADSHEET presentation.

If no handler claims the document, UiReportRunnerImpl falls back to the standard download via ReportDownloader. This means the result-handling pipeline is open for extension: a project can add @Component-level handlers (with @Order) to intercept output for custom channels (e-mail, S3 upload, in-app viewer, etc.) without modifying the runner.

---

Report Presentation Registry

ReportPresentationRegistry is the central service that resolves the active presentation for a run context, wraps a context to target a specific presentation, and applies the presentation's defaults (template, output type) before execution:

// Run a report and force the spreadsheet viewer:
UiReportRunContext spreadsheetCtx = reportPresentationRegistry.createRunContext(
        uiReportRunner.byReportEntity(report)
                .withParametersDialogShowMode(ParametersDialogShowMode.IF_REQUIRED)
                .buildContext(),
        ReportExecutionPresentationIds.SPREADSHEET);
uiReportRunner.runAndShow(spreadsheetCtx);

The registry is internal API. Premium and user code that needs to open a report in the spreadsheet should use the public SpreadsheetReportRunner helper:

@Autowired
protected SpreadsheetReportRunner spreadsheetReportRunner;

public void onClick() {
    spreadsheetReportRunner.runAndShow(
            uiReportRunner.byReportEntity(report).buildContext());
}

---

ReportSpreadsheetView

ReportSpreadsheetView is the dialog view that hosts the Vaadin Spreadsheet component. It accepts either a byte[] content (generated report output) or a stored FileRef (an execution-history record), reads the workbook into the spreadsheet, and provides:

• a Download button that exports the current workbook state (including user edits) via ReportDownloader,
• a Close action,
• automatic extension resolution (HSSF → xls, XSSF → xlsx) for the downloaded file.

The view is registered in the application context via ReportsSpreadsheetFlowUiConfiguration, which scans the io.jmix.reportsspreadsheetflowui.view package.

---

Module structure

The auto-configuration is gated by @ConditionalOnClass (checks for ReportsFlowuiConfiguration, VaadinSpreadsheetConfiguration, com.vaadin.flow.component.spreadsheet.Spreadsheet) and @ConditionalOnBean(UiReportRunner), so dropping the dependency on the classpath is sufficient to enable the feature, and missing any prerequisite cleanly deactivates the module.

---

Useful resources

• Vaadin Spreadsheet documentation
• Jmix Reports add-on
• Apache POI workbook API