Skip to content

Commit d9b1b9f

Browse files
mlopezFCmlopezFC
committed
docs: document migration to DownloadHandler API
1 parent 4e6c31c commit d9b1b9f

File tree

2 files changed

+217
-0
lines changed

2 files changed

+217
-0
lines changed

‎MIGRATION_GUIDE.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Migration Guide: StreamResource to DownloadHandler
2+
3+
## Overview
4+
5+
Starting with version 2.6.0, Grid Exporter Add-on introduces new `DownloadHandler`-based methods to replace the deprecated `StreamResource` methods. This migration is necessary for compatibility with Vaadin 25, where `StreamResource` will be removed.
6+
7+
## What's Changing?
8+
9+
The Grid Exporter Add-on now provides two sets of methods:
10+
11+
- **Old API (Deprecated)**: Methods returning `StreamResource` or `GridExporterStreamResource`
12+
- **New API (Recommended)**: Methods returning `DownloadHandler`
13+
14+
## Backward Compatibility
15+
16+
✅ **Your existing code will continue to work!** The old methods are deprecated but still functional. You can migrate at your own pace.
17+
18+
## Migration Steps
19+
20+
### 1. Update Vaadin Version
21+
22+
The new `DownloadHandler` API requires **Vaadin 24.8.0 or later**.
23+
24+
**pom.xml:**
25+
```xml
26+
<properties>
27+
<vaadin.version>24.8.0</vaadin.version>
28+
</properties>
29+
```
30+
31+
### 2. Update Method Calls
32+
33+
Replace the deprecated `get*StreamResource()` methods with the new `get*DownloadHandler()` methods.
34+
35+
#### Excel Export
36+
37+
**Before:**
38+
```java
39+
Anchor excelLink = new Anchor("", FontAwesome.Regular.FILE_EXCEL.create());
40+
excelLink.setHref(exporter.getExcelStreamResource());
41+
excelLink.getElement().setAttribute("download", true);
42+
```
43+
44+
**After:**
45+
```java
46+
Anchor excelLink = new Anchor("", FontAwesome.Regular.FILE_EXCEL.create());
47+
excelLink.setHref(exporter.getExcelDownloadHandler());
48+
excelLink.getElement().setAttribute("download", true);
49+
```
50+
51+
#### DOCX Export
52+
53+
**Before:**
54+
```java
55+
exporter.getDocxStreamResource()
56+
exporter.getDocxStreamResource(customTemplate)
57+
```
58+
59+
**After:**
60+
```java
61+
exporter.getDocxDownloadHandler()
62+
exporter.getDocxDownloadHandler(customTemplate)
63+
```
64+
65+
#### PDF Export
66+
67+
**Before:**
68+
```java
69+
exporter.getPdfStreamResource()
70+
exporter.getPdfStreamResource(customTemplate)
71+
```
72+
73+
**After:**
74+
```java
75+
exporter.getPdfDownloadHandler()
76+
exporter.getPdfDownloadHandler(customTemplate)
77+
```
78+
79+
#### CSV Export
80+
81+
**Before:**
82+
```java
83+
exporter.getCsvStreamResource()
84+
```
85+
86+
**After:**
87+
```java
88+
exporter.getCsvDownloadHandler()
89+
```
90+
91+
### 3. Update Custom Export Links (if applicable)
92+
93+
If you're creating custom export links instead of using auto-attached buttons:
94+
95+
**Before:**
96+
```java
97+
GridExporter<Person> exporter = GridExporter.createFor(grid);
98+
exporter.setAutoAttachExportButtons(false);
99+
100+
Anchor customLink = new Anchor("", "Download Excel");
101+
customLink.setHref(exporter.getExcelStreamResource().forComponent(customLink));
102+
```
103+
104+
**After:**
105+
```java
106+
GridExporter<Person> exporter = GridExporter.createFor(grid);
107+
exporter.setAutoAttachExportButtons(false);
108+
109+
Anchor customLink = new Anchor("", "Download Excel");
110+
customLink.setHref(exporter.getExcelDownloadHandler());
111+
// Note: forComponent() is handled internally for DownloadHandler
112+
```
113+
114+
## API Comparison
115+
116+
| Old Method (Deprecated) | New Method | Notes |
117+
|------------------------|------------|-------|
118+
| `getExcelStreamResource()` | `getExcelDownloadHandler()` | Excel export |
119+
| `getExcelStreamResource(String)` | `getExcelDownloadHandler(String)` | Excel with template |
120+
| `getDocxStreamResource()` | `getDocxDownloadHandler()` | DOCX export |
121+
| `getDocxStreamResource(String)` | `getDocxDownloadHandler(String)` | DOCX with template |
122+
| `getPdfStreamResource()` | `getPdfDownloadHandler()` | PDF export |
123+
| `getPdfStreamResource(String)` | `getPdfDownloadHandler(String)` | PDF with template |
124+
| `getCsvStreamResource()` | `getCsvDownloadHandler()` | CSV export |
125+
126+
## Features Preserved
127+
128+
All existing features continue to work with the new API:
129+
130+
- ✅ Concurrent download control
131+
- ✅ Download timeouts
132+
- ✅ Button disable/enable during download
133+
- ✅ Custom templates
134+
- ✅ All export formats (Excel, DOCX, PDF, CSV)
135+
- ✅ Custom columns and headers
136+
- ✅ Hierarchical data support
137+
138+
## Timeline
139+
140+
- **Version 2.6.0**: New `DownloadHandler` methods introduced, old methods deprecated
141+
- **Version 3.0.0**: Old `StreamResource` methods will be removed
142+
143+
## Need Help?
144+
145+
If you encounter any issues during migration, please:
146+
1. Check that you're using Vaadin 24.8.0 or later
147+
2. Review the deprecation warnings in your IDE
148+
3. Open an issue on [GitHub](https://github.com/FlowingCode/GridExporterAddon/issues)
149+
150+
## Example: Complete Migration
151+
152+
**Before (Version 2.5.x):**
153+
```java
154+
Grid<Person> grid = new Grid<>(Person.class);
155+
grid.setItems(people);
156+
157+
GridExporter<Person> exporter = GridExporter.createFor(grid);
158+
// Auto-attached buttons use StreamResource internally
159+
```
160+
161+
**After (Version 2.6.0+):**
162+
```java
163+
Grid<Person> grid = new Grid<>(Person.class);
164+
grid.setItems(people);
165+
166+
GridExporter<Person> exporter = GridExporter.createFor(grid);
167+
// Auto-attached buttons now use DownloadHandler internally
168+
// No code changes needed if using auto-attached buttons!
169+
```
170+
171+
**Custom Implementation:**
172+
```java
173+
Grid<Person> grid = new Grid<>(Person.class);
174+
grid.setItems(people);
175+
176+
GridExporter<Person> exporter = GridExporter.createFor(grid);
177+
exporter.setAutoAttachExportButtons(false);
178+
179+
// Create custom export buttons
180+
Anchor excelBtn = new Anchor("", "Excel");
181+
excelBtn.setHref(exporter.getExcelDownloadHandler());
182+
excelBtn.getElement().setAttribute("download", true);
183+
184+
Anchor pdfBtn = new Anchor("", "PDF");
185+
pdfBtn.setHref(exporter.getPdfDownloadHandler());
186+
pdfBtn.getElement().setAttribute("download", true);
187+
188+
add(excelBtn, pdfBtn);
189+
```

‎README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,34 @@ To see the demo, navigate to http://localhost:8080/
5454

5555
See [here](https://github.com/FlowingCode/GridExporterAddon/releases)
5656

57+
## Migration to DownloadHandler API (Version 2.6.0+)
58+
59+
**Important for Vaadin 25 compatibility**: Starting with version 2.6.0, Grid Exporter Add-on introduces new `DownloadHandler`-based methods to replace the deprecated `StreamResource` methods.
60+
61+
### Quick Migration
62+
63+
**Old API (Deprecated):**
64+
```java
65+
exporter.getExcelStreamResource()
66+
exporter.getDocxStreamResource()
67+
exporter.getPdfStreamResource()
68+
exporter.getCsvStreamResource()
69+
```
70+
71+
**New API (Recommended):**
72+
```java
73+
exporter.getExcelDownloadHandler()
74+
exporter.getDocxDownloadHandler()
75+
exporter.getPdfDownloadHandler()
76+
exporter.getCsvDownloadHandler()
77+
```
78+
79+
### Requirements
80+
81+
- **Vaadin 24.8.0 or later** is required to use the new `DownloadHandler` methods
82+
- Old `StreamResource` methods will continue to work until version 3.0.0
83+
- See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for detailed migration instructions
84+
5785
## Issue tracking
5886

5987
The issues for this add-on are tracked on its github.com page. All bug reports and feature requests are appreciated.

0 commit comments

Comments
 (0)