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 Definition essentially contains 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
User can provide their own reports, either at design-time (through Export State) or at run-time (via the Report Wizard).
Each User Report will have its own column definition and row query.
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:
A report can be sent to a number of different locations including:
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
exportDestinations of Export Options to change this by providing a custom list.
If the 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, needs to 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
via an Adaptable Form
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:
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.
Export Entitlement Rules:
Full: All Reports can be run and User Reports can be created / updated / deleted
Hidden: Reports can be run but not edited
ReadOnly: The Module is completely hidden from the User
Export Options provides a number of properties that allow you to set how Export works:
|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|
|exportDestinations||Export destinations to use; leave blank for all, empty array for none||'Excel', 'CSV', 'Clipboard', 'JSON'|
|exportFormatType||Format of exported values; can be set either for whole grid or specifically for each column type||rawValue|
|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 Export Predefined Config allows developers to pre-populate their State with Reports, Custom Destinations and much else.
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
The Export Api 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|
|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