Custom Report Export Pattern
Overview
A report page and a Home dashboard report widget show Export to CSV and Export to Excel buttons in the report header. By default the platform builds the file from the report configuration. For a custom widget report this does not always fit: for example, a Program that returns running totals per month can end up with the months added together in the file.
A custom widget can give the header its own export data. The header keeps drawing the buttons, and both buttons write the data the widget gave. If the widget gives nothing, the export is the standard one.
The widget does this with pageContext.registerExport.
When to Use
- The file the platform builds from the report configuration has the wrong numbers or the wrong layout for your widget.
- You want the file to look like the standard report export (for example one row per month and one column per category).
- You do not need this when the standard export is already correct. A widget that never calls
registerExportis exported exactly as before.
Applicable Layout Types
| Target | Notes |
|---|---|
ReportLayout | Report pages, and report widgets shown on the Home dashboard. registerExport is in pageContext. |
Other targets do not get registerExport.
How It Works
| Part | Who does it |
|---|---|
| Drawing the Export to CSV and Export to Excel buttons | The platform (report header). The widget draws no button. |
| Showing or hiding each button | The platform, by the layout template widget settings Export to CSV (config.allowExportToCsv) and Export to Excel (config.allowFilterExportInExcel). |
| The rows, the headers and the file name | The widget, through registerExport. |
| The Excel filter details sheet | The platform (it is not changed). |
| The CSV button inside a drill-down popup | The widget, with ExportCSVButton (see Bucket-Based Drill-Down Report). |
registerExport — Signature
pageContext.registerExport(getter); // give the export data
pageContext.registerExport(null); // remove it again
// getter() returns:
{
data, // Array of row objects, keyed like the headers
headers, // Array of { label, key } (the order is the column order)
fileName, // Optional. File name without extension. Default: the platform's name
}
- The getter is called by the header each time it draws the buttons, so it always reads the current rows.
dataandheadersare both required. If one is missing, the platform exports the standard way.registerExportisundefinedon a page that does not support it (an older SPA, or a target that is not a report). Always check it before calling.
Code Example — Long Layout (one row per bucket)
Month, category and count in three columns, built from the Program's rows in pageContext.totalData.
function MyReportWidget(pageContext) {
const { totalData = [], registerExport } = pageContext;
// One export row per bucket.
const exportRows = React.useMemo(
() =>
totalData.map((row) => ({
month: row.monthLabel,
category: row.category,
count: row.instanceCount,
})),
[totalData]
);
const exportHeaders = [
{ label: 'Month', key: 'month' },
{ label: 'Category', key: 'category' },
{ label: 'Count', key: 'count' },
];
React.useEffect(() => {
if (typeof registerExport !== 'function') {
return undefined; // older SPA: the platform keeps its own export
}
registerExport(() => ({
data: exportRows,
headers: exportHeaders,
fileName: 'My_Report',
}));
return () => registerExport(null); // widget removed: back to the standard export
}, [registerExport, exportRows]);
// ...render the report as usual. No export button is needed here.
}
The file:
Month,Category,Count
"Oct-2025","Keys",1874
"Nov-2025","Keys",2194
Code Example — Wide Layout (one row per month, one column per category)
Same layout as a standard pivot table export. The headers are built from the data, so a new category becomes a new column without a code change.
const categories = React.useMemo(
() => [...new Set(totalData.map((row) => row.category))],
[totalData]
);
const months = React.useMemo(
() => [...new Set(totalData.map((row) => row.monthLabel))],
[totalData]
);
const exportHeaders = React.useMemo(
() => [
{ label: 'Month', key: 'month' },
...categories.map((category) => ({ label: category, key: category })),
],
[categories]
);
const exportRows = React.useMemo(
() =>
months.map((month) => {
const row = { month };
totalData
.filter((r) => r.monthLabel === month)
.forEach((r) => {
row[r.category] = r.instanceCount;
});
return row;
}),
[months, totalData]
);
The file:
Month,Keys,Certificates
"Oct-2025",1874,52
"Nov-2025",2194,121
Notes
- One registration is enough for both buttons. The CSV and the Excel export write the same rows and headers. The Excel file also keeps the platform's filter details sheet.
- Fallback. With no registration, with
registerExport(null), or with an incomplete export (nodataor noheaders), the platform exports the standard way. An existing widget needs no change and no recompile. - Re-register when the data changes. Put the rows and the file name in the
useEffectdependencies, as in the examples. The cleanup (registerExport(null)) puts the report back on the standard export when the widget is removed. - Headers. The CSV removes HTML tags from a header label (a label
Device <br/> ClassesbecomesDevice Classes); the Excel keeps the label as it is. This is the same as the standard export. - Date columns. Use the platform's own
MMM-yyyyMonth format and the tenant time zone for a month label, as described in Bucket-Based Drill-Down Report. If a header hasattributeTypeDate,DateTimeorPicklist, also giveprefix: ''andsuffix: ''(see ExportCSVButton). - File name. Build it like the platform: type name, report name, then the date and time in the tenant time zone, for example
ResourcesReport-Resources Report Annual V1-13-10-2026 00_26. The platform adds the extension. - Buttons. Do not draw your own button for the main report export. Show or hide of the buttons is the layout template setting, the same as for every standard report.
Components Used
ExportCSVButton (only for a button inside a drill-down popup, not for the main report export).