class sap.ui.export.Spreadsheet

Control sample: sap.ui.export.Spreadsheet
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/export/Spreadsheet
Application Component: CA-UI5-TBL

Constructor

Creates a new spreadsheet export object. Use this object to build and download a spreadsheet file in Office Open XML Spreadsheet format from tabular data. This functionality is normally used together with UI5 tables.

Overview

The class builds a spreadsheet in an Office Open XML Spreadsheet format using tabular data from a specified data source. Data is retrieved and the document is built asynchronously in a worker thread of the browser. The status of the process is visually presented to the user in a progress dialog that can be suppressed. The user can cancel the process with the Cancel button of the dialog.

This class provides a low level API for spreadsheet export. The sap.ui.comp.smarttable.SmartTable control implements it internally and provides the export functionality out of the box. For special cases, please refer to details below.

Optional features:

Export settings object

Export settings should be provided in the constructor as an mSettings property map with the following fields:

Usage

To start export, create a new sap.ui.export.Spreadsheet object and call the build method. Column configuration, data source, and export settings must be provided in the constructor. The build method opens a progress dialog and starts an asynchronous export process. The export process fetches data rows from the data source, builds a spreadsheet in-browser in a worker thread, and finally downloads the document to the client.

Example:

  var oSpreadsheet = new sap.ui.export.Spreadsheet(mSettings);
  oSpreadsheet.build();

Optionally, you can attach onprogress event listeners to be notified about the export progress and follow the completion status of the returned Promise.

Example:

  var oSpreadsheet = new sap.ui.export.Spreadsheet(mSettings);
  oSpreadsheet.onprogress = function(iValue) {
  	{@link sap.base.Log#debug Log.debug}("Export: %" + iValue + " completed");
  };
  oSpreadsheet.build()
    .then( function() { {@link sap.base.Log#debug Log.debug}("Export is finished"); })
    .catch( function(sMessage) { {@link sap.base.Log#error Log.error}("Export error: " + sMessage); });

Example of column configuration:

  var aColumns = [];
  aColumns.push({
  	label: "Name",
  	property: "name"
  });
  aColumns.push({
    label: "Salary",
    property: "salary",
    type: "number",
    scale: 2
  });

  var mSettings = {
    workbook: {
      columns: aColumns,
      context: {
        application: 'Debug Test Application',
        version: '1.96.6',
        title: 'Some random title',
        modifiedBy: 'John Doe',
        metaSheetName: 'Custom metadata',
        metainfo: [
          {
            name: 'Grouped Properties',
            items: [
              { key: 'administrator', value: 'Foo Bar' },
              { key: 'user', value: 'John Doe' },
              { key: 'server', value: 'server.domain.local' }
            ]
          },
          {
            name: 'Another Group',
            items: [
              { key: 'property', value: 'value' },
              { key: 'some', value: 'text' },
              { key: 'fu', value: 'bar' }
            ]
          }
        ]
      },
      hierarchyLevel: 'level'
    },
    dataSource: mDataSource,
    fileName: "salary.xlsx"
  };
  var oSpreadsheet = new sap.ui.export.Spreadsheet(mSettings);
  oSpreadsheet.build();

Restrictions

For a complete list of restrictions, see: Spreadsheet Export Restrictions

You can export only the primitive cell data types that are listed in sap.ui.export.EdmType. Icons, images, check boxes, and complex controls in UI5 table cells are not supported.

Custom formatters in data binding are not supported.

The size of an exported table is limited by available browser memory. Export of large data sets can lead to memory overflow errors. Therefore, do not use sap.ui.export.Spreadsheet with data tables containing more than 2,000,000 table cells on desktop computers and more than 100,000 cells on mobile devices. Consider a specialized export solution in such cases. For example, MS Excel® can import spreadsheets from an OData services directly, without any UI.

The export process runs in a worker thread whenever possible. However, code injection to native XMLHttpRequest events is not available in the worker environment. Therefore, the worker parameter in export settings should be set to false if the application uses a mock server to fetch table data.

For exporting hierarchy level information, the maximum hierarchy depth is 8. This restriction results from the Office Open XML standard and the programs that can open such files. The sap.ui.export.Spreadsheet allows you to export more hierarchy levels although they might not be displayed correctly when opening the generated file if the hierarchy depth exceeds the value of 8.

The column configuration must contain at least one column to execute the export process. If there is no column configured, the export will be canceled.

If the export is used within a table, any row that is showing aggregated data (i.E. sum row) will not be exported.

The properties sheetName and metaSheetName on the workbook.context object are limited to 31 characters each. If their value exceeds this maximum length, the value will be truncated.

new sap.ui.export.Spreadsheet(mSettings)
Param Type Default Value Description
mSettings Object

Export settings

workbook Object

Spreadsheet properties

columns Array

Column configuration

context? Object

Export context that will be applied to the exported file

application? string

Application that created this XLSX

version? string

Application version that was used to create this XLSX

title? string

Title of the XLSX document (NOT the file name)

modifiedBy? string

User context for the exported document

sheetName? string

The name of the data sheet that will be shown in Excel

metaSheetName? string

The name of the metadata sheet that will be shown in Excel

metainfo? Array

Optional Metadata that will be displayed in the additional Metadata Sheet

hierarchyLevel? string

Optional name of the property that contains hierarchy level information

dataSource string Object Array sap.ui.model.ListBinding sap.ui.model.TreeBinding

Source of spreadsheet data. A JSON array, data source properties map, sap.ui.model.ListBinding, sap.ui.model.TreeBinding or URL to an OData source can be provided. For example, "someUrl" is an equivalent to {dataUrl:"someUrl", type:"OData"}. An instance of sap.ui.model.ListBinding or sap.ui.model.TreeBinding either has to implement a #getDownloadUrl function or needs to be a ClientListBinding. Note: sap.ui.model.ClientTreeBinding is not supported.

sizeLimit int

Maximal allowed number of records that can be obtained from the service in a single request

count? int

The maximal number of records to export

worker? boolean true

Run export process in a worker thread. Set to false to disable worker and run export in a main thread. This is needed, for example, if a mock server is used to provide spreadsheet data.
Note: In case of a strict content security policy, it is not always possible to create an export worker. In this case, export runs in a main thread disregarding the worker value.

fileName? string "export.xlsx"

Optional file name for the exported file

showProgress? boolean true

Set to false to suppress the progress dialog


Events Overview

Event Description
beforeSave

The beforeSave event is fired just before the generated file is saved to the file system.

Since: 1.61.

beforeSave

The beforeSave event is fired just before the generated file is saved to the file system.

Since: 1.61.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

Methods Overview

Method Description
attachBeforeSave

Attaches event handler fnFunction to the sap.ui.export.Spreadsheet#event:beforeSave event of this sap.ui.export.Spreadsheet.
When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.export.Spreadsheet itself.
This event is fired just before the generated file is saved to the file system.

cancel

Cancels a running export process. This method does nothing if no export is running.

detachBeforeSave

Detaches event handler fnFunction from the beforeSave event of this sap.ui.export.Spreadsheet.
The passed function and listener object must match the ones used for event registration.

attachBeforeSave

Attaches event handler fnFunction to the sap.ui.export.Spreadsheet#event:beforeSave event of this sap.ui.export.Spreadsheet.
When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.export.Spreadsheet itself.
This event is fired just before the generated file is saved to the file system.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnHandler function

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.export.Spreadsheet itself

cancel

Cancels a running export process. This method does nothing if no export is running.

detachBeforeSave

Detaches event handler fnFunction from the beforeSave event of this sap.ui.export.Spreadsheet.
The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnHandler function

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called