The Export Module provides a way to send data from AdapTable via saveable Reports that can be run either manually or on a schedule.
AdapTable will, by default, export the raw (i.e. underlying) value of any cell unless this is explicitly overriden
Export is not a WYSIWYG operation - AdapTable exports report data and not styles or formats.
Each Report has Row and Column Scope to allow you define precisely which Rows and Columns are exported.
There are 3 types of reports in AdapTable that you can export to multiple destinations.
Each Report contains a Definition which is essentially comprised of 2 details:
- Which Columns will be exported
- Which Rows will be exported
AdapTable ships with 5 System (i.e. predefined) Reports designed for frequently used exports:
|All Data||All Data in the Grid's Dataset||Includes filtered columns and rows|
|Current Data||All currently filtered columns and rows||Includes data not in current viewport|
|Visual Data||All currently filtered columns and rows||Exports styles and colours (to Excel only)|
|Selected Cells||Currently selected cells in the Grid||Do not need to be contiguous|
|Selected Rows||Currently selected rows in the Grid||Do not need to be contiguous|
By default all 5 System Reports will be present; use the
systemReportNames of Export Options to change this by providing a custom list.
Leave the property empty to see all 5 System reports, or provide an empty array to have none available
Users can provide their own reports which AdapTable will export to all available destinations.
Each User Report Definition will specify which columns and rows to export:
Custom Reports are different to System and User Reports as they are entirely generated at run-time by the User with no input from AdapTable.
Custon Reports do not need to include data (or columns) present in the grid in the exported data set.
Instead the data in the export is fetched each time the report is run via a function provided in Export Options
This allows you to run bespoke reports while leveraging AdapTable state, scheduling & report destinations
To define a Custom Report you need to do 4 things:
- Set the
ReportColumnScopeto CustomColumns in Export Config
- Set the
ReportRowScopeto CustomRows in Export Config
- Provide an entry for the CustomReport in the
customReportssection of Export Options
CustomReport is a basic object with just 2 properties:
|name||Name of the Report|
|onRunReport||Function invoked to return the data (in the form of a |
The ReportData object is defined as follows:
|columns||Columns in the Report|
|rows||Rows in the Report|
|columnId||Name of Column in underlying grid (e.g. field or colId)|
|dataType||DataType of the column|
|friendlyName||How Column is referred to in Adaptable UI; 'Caption' or 'Header' property in underlying grid|
rows property is defined as follows:
System Export Destinations
A report can be sent to a number of different locations including:
Excel Export is only available when using AG Grid Enterprise and the correct modules are loaded
The Export to JSON sends the data using the ReportData format
and also - depending on whether the appropriate plugin is loaded:
By default all 4 Export Destinations will be available; use the
systemExportDestinations of Export Options to change this by providing a custom list:
Custom Export Destinations
If the System Export Destinations offered by AdapTable are insufficient, developers can easily add their own custom report destinations via Export Options.
It contains a collection of CustomDestination objects defined as follows:
|form||Optional Adaptable Form - if provided, it must include Buttons that will execute the export|
|name||Name of Custom Destination|
|onExport||Function invoked when export is applied (used if no form is supplied)|
As can be seen there are 2 ways of providing Custom Destination information:
onExportfunction that is invoked by AdapTable automatically
If no custom information is required by the user at run-time to perform the export to the custom destination, simply provide an implementation for the
It is defined as follows:
And is used like this:
AdapTable will automatically invoke the function whenever the Custom Destination is selected in the toolbar.
Custom Destination Form
Sometimes it might be necessary to request users to provide additional information regarding the custom destination e.g. an email address.
This is done by including an Adaptable Form definition in the Custom Destination.
AdapTable will read this form definition metadata and create a form dynamically (including default values).
The form will typically include fields - with optional default values and validation - and a Button to perform the Export via its
When providing a form AdapTable will not perform the Export automatically; its your responsibility to provide a button and an
onClick function which will export the data
The Button is an AdaptableButton which has the usual disabled, hidden and onClick functions.
Each of these receive as a parameter the ExportButtonContext object which is defined as follows:
|customDestination||Custom Export destination|
|formData||Adaptable Form Data|
|report||The exported report|
|reportData||The data in the report|
If the Custom Destination forms part of a Schedule export, the same dynamic form and form fields will be displayed in the Schedule Wizard
You can schedule your exports to run at at time of your choosing or export manually whenever you want, e.g. you can create an 'End of Day' Report to run every weekeday at 17:30.
Details of the schedule are stored in the Schedule section of Adaptable State.
Export includes the following UI Elements:
Popup - Shows all the available Reports together with an option to export to a destination of the User's choice. Plus an Add button to start the Export Wizard.
Toolbar - Shows all the available Reports together with an option to export to a destination of the User's choice. Also includes a Schedule button to enable reports to be run on Schedules.
Tool Panel - Same as Toolbar above.
The ReadOnly Entitlement behaviour is that Reports can be run but Users cannot manage or suspend them.
Export Options provides a number of properties that allow you to set how Export works:
customDestinations- used to provide bespoke Export Destinations (in addition to those shipped by AdapTable).
customReports- used to run Custom Reports
exportFormatType- defines how exported data is displayed / formatted
The full definition is:
|appendFileTimestamp||Whether to add a timestamp ('yyyyMMdd_HHmmss') as a suffix to exported file name||false|
|customDestinations||User-provided Report Destinations (in addition to those shipped in AdapTable)|
|customReports||Reports run entirely by users (and not AdapTable)|
|exportDateFormat||Optional custom format for Date columns when exporting||undefined|
|exportFormatType||Format of exported values; can be set either for whole grid or specifically for each column type||rawValue|
|systemExportDestinations||Export destinations to use; leave blank for all, empty array for none||'Excel', 'CSV', 'Clipboard', 'JSON'|
|systemReportNames||System Reports to use; leave blank for all, empty array for none||'Visual Data', 'All Data', 'Current Data', 'Selected Cells', 'Selected Rows',|
A few of these properties are of interest:
By default the name of the file created is that of the Report which has been exported.
This can be amended slightly - via the
appendFileTimestamp property in Export Options - which will append a Timestamp to the name of the exported File:
The timestamp takes the form 'yyyyMMdd_HHmmss', e.g. 'All_Data_20210523_160123.xls'
By default, AdapTable exports the underlying raw data of the Grid.
This is by design as Export is primarily a data export function and (with the exception of the Visual Data report) not a WYSIWYG operation
This is generally the preferred behaviour, so that a value of 12.59 which has been formatted as "£12.59 (GBP)" will have the raw value sent to Excel, so that it can be identified as a number and treated accordingly.
However sometimes you might wish to export the formatted value of cells instead of the raw value.
This can be achieved by setting the
exportFormatType property in Export Options.
The default value for this propety is
The simplest way is to set this to
This will export whatever the formatted value of the cell is - whether provided by a ValueFormatter or ValueGetter (provided from AG Grid) or via AdapTable's Format Column Module
Alternatively you can set this property separately for each of
string so that some data types will export formatted values and others the raw value:
Dates can offer additional complexity in terms of formatting.
Sometimes it might be the case that you require to export all Dates in a particular format, irrespective of whether they are formatted or not in AdapTable.
This can be achieved by setting the
exportDateFormat property of Export Options.
If defined, this property takes precedence, and its value will be applied to all exported Date columns, regardless of the
exportFormatType (raw/formatted) or if the column has a valueFormatter defined
Export Predefined Config
The Predefined Configuration for Export contains all User-created Reports, together with the currently selected Report and Destination.
|CurrentDestination||Currently selected Report Destination in Export Toolbar & Tool Panel|
|CurrentReport||Currently selected Report - in Export Toolbar & Tool Panel|
|Reports||User-created Reports; each has Name and Row and Column Scope|
Reports property refers to User Reports; use the
systemReportNames property in Export Options to set which System Reports will be automatically available to users
The Report object has these properties:
|Name||Name of Report|
|Query||Query to use; only required if |
|ReportColumnScope||Columns to display in Report|
|ReportRowScope||Rows to export when Report runs|
|Scope||Columns Scope; only required if |
Report Row Scope
ReportRowScope property defines which rows are included in the report.
The options are:
AllRows - all rows in the DataSource
VisibleRows - all rows in the Grid when the Report is run
Includes all filtered rows, i.e. rows not in the current view port but which can be scrolled to
SelectedCells - all cells currently selected
Selected Cells do not need to be contiguous
SelectedRows - all cells in all currently selected rows
Selected Rows do not need to be contiguous
ExpressionRows - the Query to run to evaluate which ows to include in the exported data
CustomRows - used when creating a Custom Report
Report Column Scope
ReportColumnScope property defines which columns are included in the report.
The options are:
AllColumns - all columns in the DataSource
VisibleColumns - all columns in the Grid when the Report is run
Includes all columns that can be scrolled to, even if they are not in the current view port
SelectedColumns - all columns which are currently selected
ScopeColumns - list of Columns provided by the User which uses the Scope object
If the Report is built using the UI Wizard a separate page appears to facilitate this column selection
CustomColumns - used when creating a Custom Report
In this example we have created 2 Reports
- 'My Team Big Invoice' (the currently selected one) - which exports ALL Columns and any rows where the 'InvoicedCost' Column > 1000 AND the 'Employee' column value is one of 'Robert King', 'Margaret Peacock' or 'Anne Dodsworth'
- 'End of Day' - which exports 8 named Columns and ALL Rows. Note: we have also defined a Schedule so that the 'End of Day' Report will export to Excel automatically every weekday at 17:30
This section of Adaptable API has a number of useful export-related functions:
|canExportToExcel()||If this AdapTable instance can to export to Excel; if false, the Export to Excel option will not be visible|
|editReport(report)||Edits an existing report|
|editReports(reports)||Edits existing reports|
|exportDataToExcel(reportData, fileName)||Exports data to Excel|
|exportVisualDataToExcel()||Exports data currently in grid to Excel as What-You-See-Is-What-You-Get|
|getAllCustomDestination()||Retrieves all Custom Destinations from Export Options|
|getAllReports()||Retrieves all Reports in State - both System and User-created Reports|
|getAvailableExportDestinations()||Retrieves the available export destinations|
|getAvailableSystemReports()||Retrieves System Reports section of Export State|
|getCurrentReport()||Retrieves currently selected Report|
|getCurrentReportName()||Retrieves name of currently selected Report|
|getDestinationByName(destinationName)||Retrieves Destination with the given name|
|getExportDestinationForm(destinationName)||Form Data entered by the User in the UI for a Custom Destination|
|getExportState()||Retrieves Export section from Adaptable State|
|getReportById(id)||Retrieves Report by Id|
|getReportByName(reportName)||Retrieves Report with the given name|
|getReportSchedules()||Retrieves all Report Schedules|
|isDataChangeInReport(dataChangedInfo, report)||Whether given data change affects given report|
|isExportDestinationCustom(destinationName)||If the given destination is a Custom one|
|runCustomReport(reportName)||Runs the report function of the CustomReport with the given reportName|
|sendReport(reportName, destination)||Sends a Report to a given destination|
|showExportPopup()||Opens Export popup screen|
Is the export 'live' - will it update when the grid data changes?
No - export is a one time only snapshot.
Do you include column names in the exported data?
Yes, column names are always included in the report.
Is there an option when just copying to the clipboard to exclude column names?
Not at present but this feature will be added in future releases.
Is there a limit on the number of reports that I can create?
No, reports like all other Adaptable Objects are unlimited.
Can I export the display formatted cell value in the column and not the raw value?
Yes by setting the
exportFormatType property in Export Options.
Why can I not see the Excel destination?
If you are using AG Grid then you need to be using either AG Grid Enterprise or have the 'Excel' module loaded for this option to be available.
Can I run a Report even though it will display data not in AdapTable?
Yes, use a Custom Report. Simply supply the function that will called each time the report runs and provide any data you require.
Can I hide some of the shipped Reports or Destinations?
Yes, via the
exportDestinations properties in Export Options