AdapTable Version:

Framework:

Custom Export Destinations

Summary

AdapTable System Export Destinations can be supplemented by Custom Destinations provided by developers
Custom Destinations can be provided by Developers in 2 ways:
- an onExport function that is automatically invoked by AdapTable
- an Adaptable Form when bespoke information is required by the runtime user prior to export

If the System Export Destinations provided by AdapTable are insufficient, developers can easily supply their own custom export destinations.

This is done via the customDestinations property in Export Options.

The property returns a list (either directly or via a function) of which Custom Destinations are available.

customDestinations

CustomDestination[]

User-provided Report Destinations (used in addition to those shipped in AdapTable)

CustomDestination[]

These are Export Destinations provided by developers at design-time.

The CustomDestination object is defined as follows:

Property	Description
form	Optional Adaptable Form; if provided, it must include Buttons that will execute the Export
name	Name of Custom Destination (mandatory)
onExport	Optional Function invoked when Export is applied (used if no form is supplied)

You can provide either an array of custom destinations, or provide a function which returns an array.

Hard Coded List

The simplest method is to return an array of the Custom Destinations you wish to be available:

const adaptableOptions: AdaptableOptions = {
  exportOptions: {
    customDestinations: [
      {
        name: 'Destination 1', // in practice more props will be provided
      },
      {
        name: 'Destination 2', // in practice more props will be provided
      },
    ],
  },
};

Via a Function

Alternatively, you can provide a function which returns the Custom Destinations.

The function receives context of type CustomDestinationsContext defined as follows:

Property	Description
currentLayoutName	Name of current Layout
currentReportFormat	Format of current Report
currentReportName	Name of current Report
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

// Return just 1 Custom Destination for Current Layout Report
const adaptableOptions: AdaptableOptions = {
  exportOptions: {
    exportOptions: {
      customDestinations: (context: CustomDestinationsContext) => {
        return context.currentReportName == 'Current Layout'
          ? [
              {
                name: 'Destination 1', // in practice more props will be provided
              },
            ]
          : [
              {
                name: 'Destination 1', // in practice more props will be provided
              },
              {
                name: 'Destination 2', // in practice more props will be provided
              },
            ];
      },
    },
  },
};

Note

This allows you to export grid data to email, PDF, REST Apis and other locations you require
And you can still leverage AdapTable's Reports, Expressions, Scheduling and State Management functionality

Defining a Custom Destination

The Custom Destination object is defined as follows:

Property	Description
form	Optional Adaptable Form; if provided, it must include Buttons that will execute the Export
name	Name of Custom Destination (mandatory)
onExport	Optional Function invoked when Export is applied (used if no form is supplied)

As can be seen, it has a mandatory name property, and depending on the complexity required, there are 2 (mutually exclusive) ways of providing the Custom Destination implementation:

an onExport function that is invoked by AdapTable automatically
an Adaptable Form if bespoke information is required by the runtime user prior to export

Using an `onExport` function

In this use case, the developer needs to provide an implementation for the onExport function.

This function will then be invoked by AdapTable whenever a report is exported to the Custom Destination.

Deep Dive

Using the onExport function

The onExport function receives a reportContext object (containing all the report data required) and returns void:

onExport: (reportContext: ReportContext) => void;

The ReportContext object is defined as follows:

Property	Description
reportData	Export Data for the Report
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

The reportData property is of type ReportData which contains all the data being exported:

Property	Description
columns	Columns in the Report
groupColumnIds	Group columns IDs in the Report
pivotColumnIds	Pivot columns IDs in the Report
rows	Row Data in the Report

The ReportContext object itself derives from BaseExportContext which is defined as follows:

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`

Custom Export Destination via Function

Fork Fork

This example contains a Custom Export Destination - Rest Endpoint
It provides an implementation for the onExport function, that is invoked when the Report runs
Note: the demo simply sends a System Status message with the Report's name (and console logs its data), but a "real world" application's implementation would send the data to a REST endpoint

Defining an AdapTable Form

It might sometimes be necessary for 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 display the form dynamically (including default values).

Find Out More

See Guide to defining an Adaptable Form for full details

The form can include as many field definitions as required, together with optional default values if needed.

For the form to be effective it must include a Submit Button with an onClick property that performs the Export.

Caution

When providing a form AdapTable will not perform the Export automatically
It is your responsibility to provide a button with an onClick function which will export the data

Deep Dive

Providing an AdapTable Form

The submit Button is an Adaptable Button which has the usual disabled, hidden and onClick functions.

Hint

The Button can also be used to perform validation e.g. remain disabled until the form fields are all valid.

All the button's properties will receive as a parameter the ExportFormContext object which is defined as follows:

Property	Description
customDestination	Custom Export destination
report	The exported report
reportData	The data in the report
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

The ReportData object comprises multiple properties which contain all the data being exported:

Property	Description
columns	Columns in the Report
groupColumnIds	Group columns IDs in the Report
pivotColumnIds	Pivot columns IDs in the Report
rows	Row Data in the Report

Find Out More

See the Adaptable Button Tutorial for further information on configuring Buttons

Note

Custom Destination can also be included in a Scheduled Export
The same dynamic form and its associated form fields and buttons will be displayed in the Schedule Wizard

Custom Export Destination via a Form

Fork Fork

This example contains a Custom Export Destination - Email which uses an Adaptable Form that displays automatically when the Export is invoked
The Form contains a number of input fields:
- Dropdown with pre-selected Email Addresses
- Textboxes for Subject (pre-populated) and Body
- Checkbox for Including Headers
The Form also contains validation - the Export button cannot be clicked if the Email Body input is blank
The onClick property of the Export Button simply sends the data as a System Status (but a real world example will be different)
We also removed all System Export Destinations so that only the Custom Destination is available

import {
  AdaptableButton,
  AdaptableOptions,
  ExportFormContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Export Destination: Form',
  exportOptions: {
    customDestinations: [
      {
        name: 'Email',
        form: {
          title: 'Email Settings',
          description: 'Provide email details',
          fields: [
            {
              name: 'emailAddress',
              label: 'Email Address',
              fieldType: 'select',
              options: [
                {
                  value: 'support@adaptabletools.com',
                  label: 'Support',
                },
                {
                  value: 'sales@adaptabletools.com',
                  label: 'Sales',
                },
              ],
              defaultValue: 'support@adaptabletools.com',
            },
            {
              name: 'emailSubject',
              label: 'Email Subject',
              fieldType: 'text',
              defaultValue: 'AdapTable Report Data',
            },
            {
              name: 'emailBody',
              label: 'Email Body',
              fieldType: 'text',
            },
            {
              name: 'includeHeaders',
              label: 'Include Headers',
              fieldType: 'checkbox',
            },
          ],
          buttons: [
            {
              label: 'Cancel',
            },
            {
              label: 'Export',
              buttonStyle: {
                tone: 'success',
                variant: 'raised',
              },
              disabled: (
                button: AdaptableButton<ExportFormContext>,
                context: ExportFormContext
              ) => {
                const subject: any = context.formData?.['emailSubject'];
                const body: any = context.formData?.['emailBody'];
                return subject == '' || body == '';
              },
              onClick: (
                button: AdaptableButton<ExportFormContext>,
                context: ExportFormContext
              ) => {
                // send the report to an email address
                // the context contains the report data
                const message = `Sending to Email: Report: "${context.report.Name}"
                  with format: ${context.reportData.type} to ${context.formData?.['emailAddress']}`;

                const info = `Report contains: Columns: ${context.report.ReportColumnScope}, Rows: ${context.report.ReportRowScope}`;

                context.adaptableApi.systemStatusApi.setSuccessSystemStatus(
                  message,
                  info
                );
              },
            },
          ],
        },
      },
    ],
    systemExportDestinations: [],
  },

  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Demo',
          Toolbars: ['Export', 'SystemStatus'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Export', 'SystemStatus'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Export: {
      CurrentReport: 'All Data',
      CurrentFormat: 'Excel',
    },
    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,
        },
      ],
    },
  },
};