@sapui5/sap.ui.export 1.94.0 → 1.97.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sapui5/sap.ui.export",
-	"version": "1.94.0",
+	"version": "1.97.0",
 	"description": "SAPUI5 Library sap.ui.export",
 	"homepage": "https://sap.github.io/ui5-tooling/pages/SAPUI5/",
 	"author": "SAP SE (https://www.sap.com)",

package/src/sap/ui/export/.library

@@ -1,47 +1,45 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<library xmlns="http://www.sap.com/sap.ui.library.xsd">
-
-	<name>sap.ui.export</name>
-	<vendor>SAP SE</vendor>
-	<copyright>SAPUI5
-
-		(c) Copyright 2009-2021 SAP SE. All rights reserved
-	</copyright>
-	<version>1.94.0</version>
-
-	<documentation>UI5 library: sap.ui.export</documentation>
-
-	<dependencies>
-		<dependency>
-			<libraryName>sap.ui.core</libraryName>
-		</dependency>
-	</dependencies>
-
-	<appData>
-		<!-- excludes for the JSDoc -->
-		<jsdoc xmlns="http://www.sap.com/ui5/buildext/jsdoc">
-			<exclude name="sap.ui.export.js."/>
-		</jsdoc>
-		<documentation xmlns="http://www.sap.com/ui5/buildext/documentation"
-			indexUrl="../../../../test-resources/sap/ui/export/demokit/docuindex.json" resolve="lib"/>
-		<releasenotes xmlns="http://www.sap.com/ui5/buildext/releasenotes"
-			url="../../../../test-resources/sap/ui/export/relnotes/changes-{major}.{minor}.json" resolve="lib"/>
-		<!-- excludes for the JSCoverage -->
-		<jscoverage xmlns="http://www.sap.com/ui5/buildext/jscoverage">
-			<exclude name="sap.ui.export.js."/>
-		</jscoverage>
-		<packaging xmlns="http://www.sap.com/ui5/buildext/packaging" version="2.0">
-			<module-infos>
-				<raw-module name="sap/ui/export/js/XLSXBuilder.js" requiresTopLevelScope="false" />
-			</module-infos>
-			<all-in-one>
-				<!-- exclude third party bundles and the worker code -->
-				<exclude name="sap/ui/export/js/**" />
-			</all-in-one>
-		</packaging>
-		<ownership xmlns="http://www.sap.com/ui5/buildext/ownership">
-			<component>CA-UI5-TBL</component><!-- default component for library -->
-		</ownership>
-	</appData>
-
-</library>
+<?xml version="1.0" encoding="UTF-8" ?>
+<library xmlns="http://www.sap.com/sap.ui.library.xsd">
+
+	<name>sap.ui.export</name>
+	<vendor>SAP SE</vendor>
+	<copyright>SAPUI5
+ * (c) Copyright 2009-2021 SAP SE. All rights reserved.</copyright>
+	<version>1.97.0</version>
+
+	<documentation>UI5 library: sap.ui.export</documentation>
+
+	<dependencies>
+		<dependency>
+			<libraryName>sap.ui.core</libraryName>
+		</dependency>
+	</dependencies>
+
+	<appData>
+		<!-- excludes for the JSDoc -->
+		<jsdoc xmlns="http://www.sap.com/ui5/buildext/jsdoc">
+			<exclude name="sap.ui.export.js."/>
+		</jsdoc>
+		<documentation xmlns="http://www.sap.com/ui5/buildext/documentation"
+			indexUrl="../../../../test-resources/sap/ui/export/demokit/docuindex.json" resolve="lib"/>
+		<releasenotes xmlns="http://www.sap.com/ui5/buildext/releasenotes"
+			url="../../../../test-resources/sap/ui/export/relnotes/changes-{major}.{minor}.json" resolve="lib"/>
+		<!-- excludes for the JSCoverage -->
+		<jscoverage xmlns="http://www.sap.com/ui5/buildext/jscoverage">
+			<exclude name="sap.ui.export.js."/>
+		</jscoverage>
+		<packaging xmlns="http://www.sap.com/ui5/buildext/packaging" version="2.0">
+			<module-infos>
+				<raw-module name="sap/ui/export/js/XLSXBuilder.js" requiresTopLevelScope="false" />
+			</module-infos>
+			<all-in-one>
+				<!-- exclude third party bundles and the worker code -->
+				<exclude name="sap/ui/export/js/**" />
+			</all-in-one>
+		</packaging>
+		<ownership xmlns="http://www.sap.com/ui5/buildext/ownership">
+			<component>CA-UI5-TBL</component><!-- default component for library -->
+		</ownership>
+	</appData>
+
+</library>

package/src/sap/ui/export/ExportBase.js

@@ -0,0 +1,197 @@
+/*!
+ * SAPUI5
+ * (c) Copyright 2009-2021 SAP SE. All rights reserved.
+ */
+
+sap.ui.define([
+	'sap/ui/core/Core',
+	'sap/ui/base/EventProvider',
+	'sap/base/Log',
+	'sap/ui/export/ExportUtils'
+], function(Core, EventProvider, Log, ExportUtils) {
+	'use strict';
+
+	/**
+	 * @constructor The <code>sap.ui.export.ExportBase</code> class allows you to export table data from a UI5 application to a Portable Document Format (*.PDF) file.
+	 *
+	 * @author SAP SE
+	 * @version 1.97.0
+	 *
+	 * @since 1.96
+	 * @name sap.ui.export.ExportBase
+	 * @extends sap.ui.base.EventProvider
+	 * @public
+	 */
+	var ExportBase = EventProvider.extend('sap.ui.export.ExportBase', {
+
+		constructor: function(mSettings) {
+			EventProvider.call(this, mSettings);
+
+			/* Default settings */
+			this._mSettings = {
+				fileName: 'Export'
+			};
+
+			/* Only apply supported properties */
+			// IMPORTANT: keep count before dataSource to ensure that the expected count can be used for dataSource string
+			['count', 'dataSource', 'fileName', 'fileType', 'workbook'].forEach(function(sProperty) {
+				if (typeof mSettings[sProperty] !== 'undefined') {
+					this._mSettings[sProperty] = sProperty !== 'dataSource' ? mSettings[sProperty] : this.processDataSource(mSettings[sProperty]);
+				}
+			}.bind(this));
+		}
+	});
+
+	/**
+	 * The <code>beforeExport</code> event is fired just before the export process is started.
+	 *
+	 * @name sap.ui.export.ExportBase#beforeExport
+	 * @event
+	 * @param {sap.ui.base.Event} oEvent
+	 * @param {sap.ui.base.EventProvider} oEvent.getSource
+	 * @param {object} oEvent.getParameters
+	 * @param {ArrayBuffer} oEvent.getParameter.exportSettings - Contains export-related configuration
+	 *
+	 * @since 1.96
+	 * @public
+	 */
+
+	/**
+	 * Attaches event handler <code>fnFunction</code> to the {@link sap.ui.export.ExportBase#event:beforeExport}
+	 * event of this <code>sap.ui.export.ExportBase</code>.</br>
+	 * When called, the context of the event handler (its <code>this</code>) will be bound to <code>oListener</code> if specified,
+	 * otherwise it will be bound to this <code>sap.ui.export.ExportBase</code> itself.</br>
+	 * This event is fired just before the export process is started.
+	 *
+	 * @param {object} [oData] An application-specific payload object that will be passed to the event handler along with the event object when firing the event
+	 * @param {function} fnHandler The function to be called when the event occurs
+	 * @param {object} [oListener] Context object to call the event handler with. Defaults to the <code>sap.ui.export.ExportBase</code> instance itself
+	 *
+	 * @returns {this} Reference to <code>this</code> in order to allow method chaining
+	 *
+	 * @name sap.ui.export.ExportBase#attachBeforeExport
+	 * @function
+	 * @since 1.96
+	 * @public
+	 */
+	 ExportBase.prototype.attachBeforeExport = function(oData, fnHandler, oListener) {
+		return this.attachEvent('beforeExport', oData, fnHandler, oListener);
+	};
+
+	/**
+	 * Detaches event handler <code>fnFunction</code> from the {@link sap.ui.export.ExportBase#event:beforeExport}
+	 * event of this <code>sap.ui.export.ExportBase</code>.</br>
+	 * The passed function and listener object must match the ones used for event registration.
+	 *
+	 * @param {function} fnHandler The function to be called when the event occurs
+	 * @param {object} [oListener] Context object on which the given function had to be called
+	 *
+	 * @returns {this} Reference to <code>this</code> in order to allow method chaining
+	 *
+	 * @name sap.ui.export.ExportBase#detachBeforeExport
+	 * @function
+	 * @since 1.96
+	 * @public
+	 */
+	 ExportBase.prototype.detachBeforeExport = function(fnHandler, oListener) {
+		return this.detachEvent('beforeExport', fnHandler, oListener);
+	};
+
+	/**
+	 * Cleans up the internal structures and removes all event handlers.
+	 *
+	 * The object must not be used anymore after destroy was called.
+	 *
+	 * @see sap.ui.base.Object#destroy
+	 * @public
+	 */
+	 ExportBase.prototype.destroy = function() {
+		EventProvider.prototype.destroy.apply(this, arguments);
+
+		this.cancel();
+		this.bIsDestroyed = true;
+	};
+
+	/**
+	 * Cancels the current export process.
+	 *
+	 * @function
+	 * @abstract
+	 * @name sap.ui.export.ExportBase#cancel
+	 * @public
+	 */
+	ExportBase.prototype.cancel = function() {
+		throw new Error('Abstract function not implemented');
+	};
+
+	/**
+	 * Sets the data source configuration that will be used for exporting the data. If the passed parameter is null,
+	 * the call will be ignored.
+	 *
+	 * @param {Object|sap.ui.model.ListBinding|sap.ui.model.TreeBinding} oDataSource Possible types are a data
+	 * source configuration, a <code>sap.ui.model.ListBinding</code> or <code>sap.ui.model.TreeBinding</code>
+	 * @returns {Object|null} - Valid dataSource object or null in case the dataSource configuration is not supported
+	 *
+	 * @function
+	 * @abstract
+	 * @name sap.ui.export.ExportBase#processDataSource
+	 * @public
+	 */
+	ExportBase.prototype.processDataSource = function(oDataSource) {
+		throw new Error('Abstract function not implemented');
+	};
+
+	/**
+	 * Applies default settings to the export configuration.
+	 *
+	 * @param {Object} mSettings Export settings that will be adjusted
+	 *
+	 * @function
+	 * @abstract
+	 */
+	ExportBase.prototype.setDefaultExportSettings = function(mSettings) {
+		throw new Error('Abstract function not implemented');
+	};
+
+	/**
+	 * Creates a Promise that will be resolved after the export has been finished.
+	 *
+	 * @param {Object} mSettings Validated export configuration
+	 *
+	 * @function
+	 * @abstract
+	 */
+	ExportBase.prototype.createBuildPromise = function(mSettings) {
+		throw new Error('Abstract function not implemented');
+	};
+
+	/**
+	 * Triggers the export process of the specific format.
+	 *
+	 * @returns {Promise} Promise that gets resolved once the data has been exported
+	 *
+	 * @function
+	 * @name sap.ui.export.ExportBase#build
+	 * @public
+	 */
+	 ExportBase.prototype.build = function() {
+		var mParameters = this._mSettings;
+
+		if (this.bIsDestroyed) {
+			var sMessage = this.getMetadata().getName() + ': Cannot trigger build - the object has been destroyed';
+
+			Log.error(sMessage);
+			return Promise.reject(sMessage);
+		}
+
+		return this.setDefaultExportSettings(mParameters).then(function() {
+			this.fireEvent('beforeExport', {exportSettings: mParameters}, false, false);
+
+			ExportUtils.validateSettings(mParameters);
+
+			return this.createBuildPromise(mParameters);
+		}.bind(this));
+	};
+
+    return ExportBase;
+});

package/src/sap/ui/export/ExportUtils.js

@@ -25,7 +25,8 @@ sap.ui.define([
 ], function(coreLibrary, mLibrary, library, Core, Log, uid, Item, syncStyleClass, JSONModel, Button, CheckBox, Dialog, Input, Label, Select, Text, VBox, VersionInfo, openWindow) {
 	'use strict';
 
-	/*global Blob, MouseEvent, FileReader, URL */
+	// eslint-disable-next-line
+	/* global Blob, MouseEvent, FileReader, URL */
 
 	// Shortcuts
 	var ButtonType = mLibrary.ButtonType;
@@ -53,7 +54,7 @@ sap.ui.define([
 	});
 
 	/* Returns the Export Settings used by the User Settings Dialog */
-	function getExportSettings(oCustomConfig, oResourceBundle) {
+	function getExportSettings(oCustomConfig, oResourceBundle, bDevMode) {
 		var sSelectedKey;
 		var oDefaultConfig = {
 			fileName: 'Standard',
@@ -66,6 +67,10 @@ sap.ui.define([
 			addDateTime: false
 		};
 
+		if (bDevMode) {
+			oDefaultConfig.fileType.push({key: 'pdf'});
+		}
+
 		var oExportConfig = Object.assign({}, oDefaultConfig, oCustomConfig || {});
 
 		for (var i = 0; i < oExportConfig.fileType.length; i++) {
@@ -89,7 +94,7 @@ sap.ui.define([
 	 * Utilities related to export to enable reuse in integration scenarios (e.g. tables).
 	 *
 	 * @author SAP SE
-	 * @version 1.94.0
+	 * @version 1.97.0
 	 *
 	 * @since 1.59
 	 * @name sap.ui.export.ExportUtils
@@ -126,25 +131,37 @@ sap.ui.define([
 			return sUrl;
 		},
 
+		/**
+		 * Ensures that the URL is absolute, so that it can
+		 * be used within a Web Worker.
+		 *
+		 * @param {string} url Relative URL that needs to be processed for Web Worker usage
+		 * @returns {string|any} Returns the absolute URL or the original value in case there is no URL provided
+		 */
+		normalizeUrl: function(url) {
+			return url ? new URL(url, document.baseURI).toString() : url;
+		},
+
 		/**
 		 * Creates the Export settings dialog that can be used for configuring the spreadsheet before exporting.
 		 *
 		 * @param {Object} mCustomConfig Initial configuration of the settings dialog
 		 * @param {sap.ui.core.Control} oOpener The opener of the dialog
 		 * @param {function} [fnCallback] Handler function that is called once the dialog has been opened. A reference to the dialog is passed as parameter
+		 * @param {boolean} [bDevMode] Flag that allows to activate settings that are currently in development
 		 *
 		 * @returns {Promise} Promise which resolves with the export settings defined by the user
 		 *
 		 * @static
 		 */
-		getExportSettingsViaDialog: function(mCustomConfig, oOpener, fnCallback) {
+		getExportSettingsViaDialog: function(mCustomConfig, oOpener, fnCallback, bDevMode) {
 			return new Promise(function (fnResolve, fnReject) {
 				var oExportSettingsDialog;
 
 				oResourceBundlePromise.then(function (oResourceBundle) {
 
 					var oExportConfigModel = new JSONModel();
-					oExportConfigModel.setData(getExportSettings(mCustomConfig, oResourceBundle));
+					oExportConfigModel.setData(getExportSettings(mCustomConfig, oResourceBundle, bDevMode));
 
 					var sDialogId = uid();
 
@@ -191,7 +208,7 @@ sap.ui.define([
 									new Label({
 										text: oResourceBundle.getText('SELECT_FORMAT'),
 										labelFor: sDialogId + '-fileType',
-										visible: false
+										visible: !!bDevMode
 									}),
 									// sap.m.Select control disabled as there is only 1 option for now
 									// control must be enabled when more file types are supported
@@ -199,11 +216,11 @@ sap.ui.define([
 										id: sDialogId + '-fileType',
 										width: '100%',
 										selectedKey: '{/selectedFileType}',
-										visible: false,
 										items: {
 											path: '/fileType',
 											template: new Item({key: '{key}', text: '{text}'})
-										}
+										},
+										visible: !!bDevMode
 									}),
 									new CheckBox({
 										id: sDialogId + '-splitCells',
@@ -273,7 +290,7 @@ sap.ui.define([
 		 * Combines the filter operator with the value and
 		 * creates a textual representation.
 		 *
-		 * @param oFilter {Object} A single filter object according to ListBinding#getFilterInfo
+		 * @param {Object} oFilter A single filter object according to ListBinding#getFilterInfo
 		 * @returns {string} Textual representation of the filter operation and value
 		 * @private
 		 */
@@ -303,7 +320,7 @@ sap.ui.define([
 		/**
 		 * Parse filter tree recursively.
 		 *
-		 * @param oFilter {Object} Filter configuration according to ListBinding#getFilterInfo
+		 * @param {Object} oFilter Filter configuration according to ListBinding#getFilterInfo
 		 * @returns {Array} Array of filter entries
 		 * @private
 		 */
@@ -326,7 +343,7 @@ sap.ui.define([
 		 * Parses a logical filter and concatenates all
 		 * subsequent filters.
 		 *
-		 * @param oLogicalFilter {Object} Filter object according to ListBinding#getFilterInfo
+		 * @param {Object} oLogicalFilter Filter object according to ListBinding#getFilterInfo
 		 * @returns {Array} Array containing all filter settings
 		 * @private
 		 */
@@ -367,7 +384,7 @@ sap.ui.define([
 		 * Parses a binary filter and returns an Array that
 		 * contains this explicit filter item.
 		 *
-		 * @param oBinaryFilter {Object} Filter object according to ListBinding#getFilterInfo
+		 * @param {Object} oBinaryFilter Filter object according to ListBinding#getFilterInfo
 		 * @returns {Array} Array containing this explicit filter setting
 		 * @private
 		 */
@@ -387,7 +404,7 @@ sap.ui.define([
 		 * Parses an unary filter and returns a modified
 		 * subsequent filter.
 		 *
-		 * @param oUnaryFilter {Object} Filter object according to ListBinding#getFilterInfo
+		 * @param {Object} oUnaryFilter Filter object according to ListBinding#getFilterInfo
 		 * @returns {Array} Array containing the modified subsequent filter
 		 * @private
 		 */
@@ -408,7 +425,7 @@ sap.ui.define([
 		 * Parses an call filter and returns an Array containing
 		 * this particular filter configuration.
 		 *
-		 * @param oCallFilter {Object} Filter object according to ListBinding#getFilterInfo
+		 * @param {Object} oCallFilter Filter object according to ListBinding#getFilterInfo
 		 * @returns {Array} Array containing this explicit filter setting
 		 * @private
 		 */
@@ -429,11 +446,8 @@ sap.ui.define([
 		 * configuration in a format that can be attached to
 		 * a sap.ui.export.Spreadsheet instance.
 		 *
-		 * @param oBinding {sap.ui.model.ListBinding | sap.ui.model.TreeBinding}
-		 * ListBinding or TreeBinding instance
-		 *
-		 * @param fnCallback {function}
-		 * Callback function that is used to resolve the columns names according to their property.
+		 * @param {sap.ui.model.ListBinding | sap.ui.model.TreeBinding} oBinding ListBinding or TreeBinding instance
+		 * @param {function} fnCallback Callback function that is used to resolve the columns names according to their property
 		 *
 		 * @returns {Promise}
 		 * Promise, which resolves with an object containing a name
@@ -650,8 +664,19 @@ sap.ui.define([
 				mDataSource.count = mDataSource.data.length;
 			}
 
-			if (mDataSource.type === 'odata' && (typeof mDataSource.dataUrl !== 'string' || mDataSource.dataUrl.length === 0)) {
-				throw new Error(CLASS_NAME + ': Unable to export data. No dataUrl provided.');
+			if (mDataSource.type === 'odata') {
+				if (typeof mDataSource.dataUrl !== 'string' || mDataSource.dataUrl.length === 0) {
+					throw new Error(CLASS_NAME + ': Unable to export data. No dataUrl provided.');
+				}
+
+				// Ensure absolute URLs for dataUrl and serviceUrl
+				if (mDataSource.dataUrl) {
+					mDataSource.dataUrl = Utils.normalizeUrl(mDataSource.dataUrl);
+				}
+
+				if (mDataSource.serviceUrl) {
+					mDataSource.serviceUrl = Utils.normalizeUrl(mDataSource.serviceUrl);
+				}
 			}
 
 			if (typeof mDataSource.count !== 'number' || mDataSource.count < 0 || isNaN(mDataSource.count) || mDataSource.count % 1 !== 0) {
@@ -886,7 +911,7 @@ sap.ui.define([
 		 *
 		 * @param {Object} oContext Context object
 		 * @param {string} [oContext.application] Name of the application (default: "SAP UI5")
-		 * @param {string} [oContext.version] Application version (default: "1.94.0")
+		 * @param {string} [oContext.version] Application version (default: "1.97.0")
 		 * @param {string} [oContext.title] Title that will be written to the file (NOT the filename)
 		 * @param {string} [oContext.modifiedBy] Optional user context that will be written to the file
 		 * @param {string} [oContext.sheetName] Name of the data sheet - Maximum length of 31 characters
@@ -990,12 +1015,16 @@ sap.ui.define([
 		 * @param {Object} oCustomizing General export customizing
 		 * @param {Object} oCustomizing.currency Currency specific customizing
 		 * @param {Object} oCustomizing.unit Unit of measure specific customizing
-		 * @param {string} sProperty Name of the property
+		 * @param {string} sProperty Key property of the specific customizing setting
 		 * @private
 		 */
 		_validateScaleCustomizing: function(oCustomizing, sProperty) {
 			var sKey, mScaleSettings;
 
+			if (!oCustomizing) {
+				return;
+			}
+
 			mScaleSettings = oCustomizing[sProperty];
 
 			if (!(mScaleSettings instanceof Object) || Array.isArray(mScaleSettings)) {
@@ -1012,6 +1041,60 @@ sap.ui.define([
 					}
 				}
 			}
+		},
+
+		/**
+		 * Returns an instance of the specific export class that is evaluated
+		 * by FileType. The default class is sap/ui/export/Spreadsheet when
+		 * no specific FileType is defined in the export settings.
+		 *
+		 * @param {Object} mSettings Export configuration with optional FileType
+		 * @returns {Promise} A Promise that gets resolved with the requested instance
+		 */
+		getExportInstance: function(mSettings) {
+			var sClassName, sFileType;
+
+			sFileType = typeof mSettings.fileType === 'string' ? mSettings.fileType.toUpperCase() : mSettings.fileType;
+
+			switch (sFileType) {
+				case FileType.PDF:
+					sClassName = 'sap/ui/export/PortableDocument';
+					break;
+				default:
+					sClassName = 'sap/ui/export/Spreadsheet';
+			}
+
+			return new Promise(function(fnResolve) {
+				sap.ui.require([sClassName], function(ExportClass) {
+					fnResolve(new ExportClass(mSettings));
+				});
+			});
+		},
+
+		/**
+		 * Returns the amount of data that is available on the backend
+		 * in case the binding provides this information.
+		 *
+		 * @param {sap.ui.model.ListBinding|sap.ui.model.TreeBinding} oBinding - A subclass of <code>sap.ui.model.ListBinding</code> or <code>sap.ui.model.TreeBinding</code>
+		 * @return {number|null} Amount of data in the backend or null if the binding does not provide this information
+		 */
+		getCountFromBinding: function(oBinding) {
+			var iCount;
+
+			if (typeof oBinding.getCount === 'function') {
+				iCount = oBinding.getCount();
+			} else if (!oBinding.isA('sap.ui.model.TreeBinding') // Explicitly exclude TreeBinding because Binding#getLength is numberOfExpandedLevels dependent
+					&& typeof oBinding.isLengthFinal === 'function'
+					&& oBinding.isLengthFinal()) {
+
+				iCount = oBinding.getLength();
+			}
+
+			if (typeof iCount !== 'number' || iCount < 0 || isNaN(iCount)) {
+				iCount = null;
+			}
+
+			return iCount;
 		}
 	};