AdapTable Version:

Framework:

Configuring Export

Summary

Developers can configure Export at design time in multiple ways

There are many aspects of Export that can be configured by developers, primarily through properties in Export Options, or functions in Export API.

Advanced Exporting

By default Export will send the report to the desired destination in a straightforward way.

For instance exporting to Excel will create a new workbook with default worksheet settings.

However sometimes users want more fine-grained control over the Exported file, e.g. to change the worksheet names, font, or other properties in Excel.

This is possible by using the exportReport function in Export API.

It takes an optional exportConfig property which allows users to modify the params being sent.

exportReport

Multiple Params

Promise<void>

Exports a Report (with fine-grained control if needed)

This function allows developers, at run time, to export Reports in AdapTable to any destination.

It also provides them with very fine-grained control over the Export.

The function definition is:

exportReport(name: ReportNameType, format: ReportFormatType, destination?: ExportDestinationType, config?: ExportConfig
): Promise<void>;

Basic Exporting

You can use this function to export a report to a destination of your choice.

// Export the Current Layout in Visual Export format as a downloadable file
adaptableApi.exportApi.exportReport('Current Layout', 'Excel', 'Download')

Advanced Exporting

The function also allows developers to configure the Export in much more depth.

This is due to the exportConfig property, which is of type ExportConfig, and defined as follows:

Property	Description
exportParams	Function to modify export params; receives default params & returns modified params
showProgressIndicator	Whether to show progress indicator

The exportParams property is a function which enables overriding of AdapTable's default export behaviour.

It receives default params (of type CustomExportParams) and returns modified params (also of type CustomExportParams):

exportParams?: (defaultExportParams: CustomExportParams) => CustomExportParams;

The CustomExportParams object can be one of two AG Grid objects:

ExcelExportParams - used for Excel format exports
CsvExportParams - used for CSV, JSON and any custom format exports

// Export to Excel but configure the Workbook and Worksheet to meet precise requirements
adaptableApi.exportApi.exportReport('Current Layout', 'Excel', 'Download',
  {
    exportParams: (exportParams: ExcelExportParams) => {
      if (!exportParams.processCellCallback) {
        return exportParams;
      }
      const adaptableProcessCellCallback = exportParams.processCellCallback;
      return {
        ...exportParams,
        fileName: 'AdapTable Data',
        author: 'AdapTable Demos',
        fontSize: 13,
        sheetName: context.adaptableApi.layoutApi.getCurrentLayoutName(),
        headerRowHeight: 50,
        processCellCallback: params => {
          // inherits adaptable formatting (Column Format, etc.)
          const adaptableCellValue = adaptableProcessCellCallback(params);
          return `Custom ${adaptableCellValue}`;
        },
      };
    },
  }
);

Configuring Export

Fork Fork

In this demo we export data to Excel and CSV via the exportReport function in Export API (using Custom Toolbar Buttons), allowing us add bespoke config:
- We export Current Layout report to Excel, with custom names for Excel Workbook and Worksheet, and changing font and header row height
- We export All Data report to CSV, with custom filename and separator

import {
  AdaptableButton,
  AdaptableOptions,
  CustomExportParams,
  CustomToolbarButtonContext,
  GridCellRange,
} from '@adaptabletools/adaptable';
import {CsvExportParams, ExcelExportParams} from 'ag-grid-enterprise';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Exporting Reports with Config',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'ButtonToolbar',
        title: 'Buttons',
        toolbarButtons: [
          {
            label: 'Export to Excel',
            icon: {
              name: 'excel',
            },
            buttonStyle: {
              tone: 'neutral',
              variant: 'outlined',
            },
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.exportApi.exportReport(
                'Current Layout',
                'Excel',
                'Download',
                {
                  exportParams: (exportParams: CustomExportParams) => {
                    if (!exportParams.processCellCallback) {
                      return exportParams;
                    }
                    const adaptableProcessCellCallback =
                      exportParams.processCellCallback;
                    return {
                      ...exportParams,
                      fileName: 'AdapTable Excel Data',
                      author: 'AdapTable Demos',
                      fontSize: 13,
                      sheetName:
                        context.adaptableApi.layoutApi.getCurrentLayoutName(),
                      headerRowHeight: 50,
                      processCellCallback: params => {
                        // inherits adaptable formatting (Column Format, etc.)
                        const adaptableCellValue =
                          adaptableProcessCellCallback(params);
                        return `Custom ${adaptableCellValue}`;
                      },
                    };
                  },
                }
              );
            },
          },
          {
            label: 'Export to CSV',
            icon: {
              name: 'csv',
            },
            buttonStyle: {
              tone: 'neutral',
              variant: 'outlined',
            },
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.exportApi.exportReport(
                'All Data',
                'CSV',
                'Download',
                {
                  exportParams: (defaultExportParams: CustomExportParams) => {
                    if (!defaultExportParams.processCellCallback) {
                      return defaultExportParams;
                    }
                    const adaptableProcessCellCallback =
                      defaultExportParams.processCellCallback;
                    return {
                      ...defaultExportParams,
                      fileName: 'AdapTable CSV Data',
                      author: 'AdapTable Demos',
                      columnSeparator: '|',
                      processCellCallback: params => {
                        // inherits adaptable formatting (Column Format, etc.)
                        const adaptableCellValue =
                          adaptableProcessCellCallback(params);
                        return `Custom ${adaptableCellValue}`;
                      },
                    };
                  },
                }
              );
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {PinnedToolbars: ['ButtonToolbar']},
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Configuring Report File Names

By default the name of the file created in an Export is that of the exported Report Name (e.g. 'All Data').

There are 2 options available in Export Options to change this behaviour:

appendFileTimestamp which appends a Timestamp to the Report name

appendFileTimestamp

Default: false

boolean

Whether to add a timestamp as a suffix to exported file name

The timestamp always takes the form 'yyyyMMdd_HHmmss'.

For example exporting the 'All Data' report on 1 Jan at 10:15 am will produce: 'All_Data_20250101_101500.xls'

// Add a Timestamp to the name of the exported report
const adaptableOptions: AdaptableOptions = {
    exportOptions: {
       appendFileTimestamp: true,
    }
}

reportFilename which allows a completely different Report name to be used

reportFilename

(reportFileNameContext: ReportFileNameContext) => boolean

Function enabling bespoke Report file names

Use this property to override AdapTable's default Report file name with a besoke implementation.

The function receives a ReportFileNameContext object and returns a boolean:

reportFilename?(reportFileNameContext: ReportFileNameContext): string;

The ReportFileNameContext object contains just 1 property:

Property	Description
fileName	Default File Name to use
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

but also extends BaseExportContext

Property	Description
exportDestination	Export Destination for the Report
report	The Report Configuration being run
reportFormat	Format of the Report being run
reportName	Name of the Report being run
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

// Change the File Name for "All Data" Report
const adaptableOptions: AdaptableOptions = {
    exportOptions: {
      reportFilename: (reportFileNameContext: ReportFileNameContext) => {
        return reportFileNameContext.reportName == 'All Data'
          ? `Current Grid Data Sent to ${
              reportFileNameContext.destination
            } on ${new Date().toDateString()}`
          : reportFileNameContext.fileName;
      },
    }
}

Configuring Report FileNames

Fork Fork

In this example we provide a custom File Name - but just for the "All Data" Report

Setting Exportable Columns

By default every Column in AdapTable is exportable.

This means that it can be included in System Reports (e.g. All Data) and will be available in UI for selection.

This can be set to false for any Column via the isColumnExportable property in Export Options.

isColumnExportable

Default: true

boolean

Whether a Column is exportable

This property is in the form of a function which takes an AdaptableColumnContext object and returns a Boolean.

isColumnExportable?: (context: AdaptableColumnContext) => boolean;

The AdaptableColumnContext simply includes details of the given column to check.

// Only allow 4 Columns to be included in Reports
const adaptableOptions: AdaptableOptions = {
  exportOptions: {
   isColumnExportable: (context: AdaptableColumnContext) =>
    ['name', 'github_stars', 'language', 'github_watchers',].includes(
      context.column.columnId
    ),
  }
}

Setting Exportable Columns

Fork Fork

In this example we dont export the Language Column, nor any Date Columns

Skipping Column Headers

By default AdapTable will include the Column Headers in the Export.

This can be set to false all or some Reports via the skipColumnHeaders property in Export Options.

skipColumnHeaders

Default: true

boolean

Whether to include Column Headers in Report

This property is in the form of a boolean or a function which takes an BaseExportContext object and returns a Boolean.

skipColumnHeaders?: boolean | ((skipColumnHeadersContext: BaseExportContext) => boolean);

The BaseExportContext provides details of the report being exported:

Property	Description
exportDestination	Export Destination for the Report
report	The Report Configuration being run
reportFormat	Format of the Report being run
reportName	Name of the Report being run
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

// Don't include Column Header in the All Data Report
const adaptableOptions: AdaptableOptions = {
  exportOptions: {
   skipColumnHeaders: (context: BaseExportContext) => {
      return context.reportName === 'All Data';
    },
  }
}