@sapui5/sap.ui.export 1.101.0 → 1.103.0

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

@@ -0,0 +1,463 @@
+/*!
+ * SAPUI5
+ * (c) Copyright 2009-2022 SAP SE. All rights reserved.
+ */
+sap.ui.define(['./library', './ExportUtils', './ExportDialog', 'sap/m/MessageToast', 'sap/ui/core/Core', 'sap/ui/base/EventProvider', 'sap/ui/model/odata/v4/ODataModel', 'sap/ui/util/openWindow'], function(library, ExportUtils, ExportDialog, MessageToast, Core, EventProvider, ODataModel, openWindow) {
+	'use strict';
+
+	var Destination = library.Destination;
+
+	/**
+	 * Any export related functionality is encapsuled in the <code>ExportHandler</code> which also stores user settings throughout the session.
+	 *
+	 * @param {object} [mCapabilities] Mapping object which references certain export capabilities
+	 * @constructor The <code>sap.ui.export.ExportHandler</code> class allows you to export table data from a UI5 application.
+	 *
+	 * @author SAP SE
+	 * @version 1.103.0
+	 *
+	 * @since 1.102
+	 * @name sap.ui.export.ExportHandler
+	 * @extends sap.ui.base.EventProvider
+	 * @namespace
+	 * @private
+	 * @ui5-restricted sap.ui.comp.smarttable.SmartTable, sap.ui.mdc.Table
+	 */
+	var ExportHandler = EventProvider.extend('sap.ui.export.ExportHandler', {
+		constructor: function(mCapabilities) {
+			EventProvider.call(this);
+
+			/* Apply default capabilities if nothing is provided */
+			this._mCapabilities = mCapabilities instanceof Object ? mCapabilities : { XLSX: {} };
+		}
+	});
+
+	/**
+	 * The <code>beforeExport</code> event is fired just before the export process is started.
+	 *
+	 * @name sap.ui.export.ExportHandler#beforeExport
+	 * @event
+	 * @param {sap.ui.base.Event} oEvent
+	 * @param {sap.ui.base.EventProvider} oEvent.getSource
+	 * @param {object} oEvent.getParameters
+	 * @param {object} oEvent.getParameter.exportSettings Contains export-related configuration
+	 * @param {object} oEvent.getParameter.userExportSettings User specific settings from the "Export As" dialog
+	 *
+	 * @since 1.102
+	 * @public
+	 */
+
+	/**
+	 * Attaches event handler <code>fnFunction</code> to the {@link sap.ui.export.ExportHandler#event:beforeExport}
+	 * event of this <code>sap.ui.export.ExportHandler</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.ExportHandler</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.ExportHandler</code> instance itself
+	 *
+	 * @returns {this} Reference to <code>this</code> in order to allow method chaining
+	 *
+	 * @name sap.ui.export.ExportHandler#attachBeforeExport
+	 * @function
+	 * @since 1.102
+	 * @public
+	 */
+	ExportHandler.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.ExportHandler#event:beforeExport}
+	 * event of this <code>sap.ui.export.ExportHandler</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.ExportHandler#detachBeforeExport
+	 * @function
+	 * @since 1.102
+	 * @public
+	 */
+	ExportHandler.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
+	 */
+	ExportHandler.prototype.destroy = function() {
+		EventProvider.prototype.destroy.apply(this, arguments);
+
+		if (this._oModel) {
+			this._oModel.destroy();
+		}
+
+		this._mCapabilities = null;
+		this._oDataSource = null;
+		this._mDialogSettings = null;
+		this._oModel = null;
+		this.bIsDestroyed = true;
+	};
+
+	/**
+	 * Loads the FileShareSupport module and requests
+	 * available destinations. If no FileShareSupport
+	 * module is registered or the module does not
+	 * provide a destination, the Promise resolves
+	 * without any result.
+	 *
+	 * @returns {Promise} A Promise that gets resolved with the FileShareSupport datasource or undefined if there is none
+	 */
+	ExportHandler.prototype.fetchDataSource = function() {
+		var that = this;
+		var sFileShareSupportModuleName;
+
+		if (this._oDataSource) {
+			return Promise.resolve(this._oDataSource);
+		}
+
+		sFileShareSupportModuleName = Core.getConfiguration().getFileShareSupport();
+
+		if (!sFileShareSupportModuleName) {
+			return Promise.resolve();
+		}
+
+		return new Promise(function(fnResolve) {
+			sap.ui.require([sFileShareSupportModuleName], function(oFileShareSupport) {
+				oFileShareSupport.getDataSource().then(function(oDataSource) {
+					that._oDataSource = oDataSource;
+					fnResolve(oDataSource);
+				}).catch(function () {
+					fnResolve();
+				});
+			});
+		});
+	};
+
+	/**
+	 * Opens the <code>CloudFilePicker</code> control and
+	 * returns a <code>Promise</code> that gets resolved
+	 * when the user selected a particular location for
+	 * the file that should be created.
+	 *
+	 * @param {object} oDataSource DataSource object containing the serviceUrl for the CloudFilePicker
+	 * @param {string} [sFileName] Suggested name of the file including file extension
+	 * @returns {Promise} Resolves with the file location selected in the <code>CloudFilePicker</code>
+	 */
+	ExportHandler.prototype.getRemoteFileLocation = function(oDataSource, sFileName) {
+		return new Promise(function(fnResolve, fnReject) {
+			ExportUtils.getResourceBundle().then(function(oResourceBundle) {
+				sap.ui.require(['sap/suite/ui/commons/CloudFilePicker'], function(CloudFilePicker) {
+					var oFilePicker;
+
+					oFilePicker = new CloudFilePicker({
+						serviceUrl: oDataSource.uri,
+						suggestedFileName: sFileName,
+						enableDuplicateCheck: true,
+						fileNameMandatory: true,
+						confirmButtonText: oResourceBundle.getText('EXPORT_BUTTON'),
+						title: oResourceBundle.getText('DESTINATION_DIALOG_TITLE')
+					});
+
+					oFilePicker.attachSelect(function(oEvent) {
+						var aSelectedFiles, oSelectedFolder, bReplaceFile, mCloudFileInfo = {};
+
+						aSelectedFiles = oEvent.getParameter('selectedFiles');
+						oSelectedFolder = oEvent.getParameter('selectedFolder');
+						bReplaceFile = oEvent.getParameter('replaceExistingFile');
+
+						mCloudFileInfo = {};
+						mCloudFileInfo['FileShare'] = oSelectedFolder.getFileShareId();
+						mCloudFileInfo['FileShareItemKind'] = 'document';
+						mCloudFileInfo['FileShareItemName'] = oEvent.getParameter('selectedFileName');
+						mCloudFileInfo['ParentFileShareItem'] = oSelectedFolder.getFileShareItemId();
+
+						if (bReplaceFile && Array.isArray(aSelectedFiles) && aSelectedFiles.length > 0) {
+							var oCloudFile = aSelectedFiles.shift();
+
+							mCloudFileInfo['FileShareItem'] = oCloudFile.getFileShareItemId();
+						}
+
+						/* Check whether the user has selected a valid FileShare */
+						if (!mCloudFileInfo['FileShare']) {
+							fnReject(oResourceBundle.getText('DESTINATION_SELECTION_INCOMPLETE'));
+						}
+
+						fnResolve(mCloudFileInfo);
+					});
+
+					oFilePicker.open();
+				});
+			});
+		});
+	};
+
+	/**
+	 * Creates an export instance according to the given file type
+	 * and adds default event handlers.
+	 *
+	 * @param {object} mExportSettings mExportSettings ExportSettings that are used for the export
+	 * @param {object} mCustomSettings Additional settings that are passed into the event
+	 * @param {object} mCloudFileInfo FileShareItem representation of the file
+	 * @returns {Promise} A Promise that resolves with the desired export instance
+	 */
+	ExportHandler.prototype.getExportInstance = function(mExportSettings, mCustomSettings, mCloudFileInfo) {
+		var that = this;
+
+		return Promise.all([
+			ExportUtils.getResourceBundle(),
+			ExportUtils.getExportInstance(mExportSettings)
+		]).then(function(aResolve) {
+			var oResourceBundle = aResolve[0];
+			var oExportInstance = aResolve[1];
+
+			oExportInstance.attachBeforeExport(function(oEvent) {
+				var mEventExportSettings = oEvent.getParameter('exportSettings');
+
+				that.fireEvent('beforeExport', {
+					exportSettings: mEventExportSettings,
+					userExportSettings: mCustomSettings || {}
+				}, false, false);
+			});
+
+			if (mCloudFileInfo && typeof oExportInstance.attachBeforeSave === 'function') {
+				oExportInstance.attachBeforeSave(function(oEvent) {
+					var aArrayBuffer, oExportDialog;
+
+					aArrayBuffer = oEvent.getParameter('data');
+					oExportDialog = oEvent.getParameter('exportDialog');
+					mCloudFileInfo['FileShareItemContentType'] = oExportInstance.getMimeType();
+
+					var uInt8Array = new Uint8Array(aArrayBuffer);
+					var stringArray = new Array(uInt8Array.length);
+					for (var i = 0; i < uInt8Array.length; i++) {
+						stringArray[i] = String.fromCharCode(uInt8Array[i]); // often a bit faster, especially with huge files, than string concatenation
+					}
+					mCloudFileInfo['FileShareItemContent'] = btoa(stringArray.join(""));
+
+					oExportDialog.updateStatus(oResourceBundle.getText('DESTINATION_DIALOG_STATUS'));
+					oEvent.preventDefault();
+
+					that.uploadFile(mCloudFileInfo).then(function() {
+						MessageToast.show(oResourceBundle.getText('DESTINATION_TRANSFER_SUCCESS'));
+					}).catch(function() {
+						ExportDialog.showErrorMessage(oResourceBundle.getText('DESTINATION_TRANSFER_ERROR'));
+					}).finally(function() {
+						oExportDialog.finish();
+					});
+				});
+			}
+
+			return oExportInstance;
+		});
+	};
+
+	/**
+	 * Uploads the file to the FileShareSupport OData service.
+	 *
+	 * @param {object} mCloudFileInfo FileShareItem representation of the file
+	 * @returns {Promise} A Promise that gets resolved after the generated file has been transferred to the FileShareSupport OData service
+	 */
+	ExportHandler.prototype.uploadFile = function(mCloudFileInfo) {
+		return this.fetchDataSource().then(function(oDestination) {
+			var oBinding, oContext, oModel, sContentProperty, sTypeProperty, sPath;
+
+			sContentProperty = "FileShareItemContent";
+			sTypeProperty = 'FileShareItemContentType';
+			oModel = this._getModel(oDestination);
+
+			/* Overwrite existing file */
+			if (mCloudFileInfo['FileShareItem']) {
+				oContext = oModel.getKeepAliveContext("/FileShareItems(FileShare='" + mCloudFileInfo.FileShare + "',FileShareItem='" + mCloudFileInfo.FileShareItem + "')");
+
+				/*
+				 * We have to set the FileShareItemContentLink as well
+				 * as the FileShareItemContentType property explicitly
+				 * to ensure that the properties will be filled with
+				 * the content of the PATCH response when updating the
+				 * FileShareItemContent. Adding the <code>null</code>
+				 * prevents an additional PATCH for the link. It is also
+				 * important to set all properties without waiting for
+				 * the Promise to resolve. This allows the binding to
+				 * bundle multiple PATCH requests into a single $batch.
+				 */
+				oContext.setProperty('FileShareItemContentLink', '', null);
+				oContext.setProperty(sTypeProperty, mCloudFileInfo[sTypeProperty]);
+				return oContext.setProperty(sContentProperty, mCloudFileInfo[sContentProperty]).then(function() {
+					return oContext.getProperty('FileShareItemContentLink');
+				});
+			}
+
+			/* Creating new file in specific folder or _Root */
+			if (mCloudFileInfo.ParentFileShareItem) {
+				sPath = "/FileShareItems(FileShare='" + mCloudFileInfo.FileShare + "',FileShareItem='" + mCloudFileInfo.ParentFileShareItem + "')/_Children";
+			} else {
+				sPath = "/FileShares(FileShare='" + mCloudFileInfo.FileShare + "')/_Root/_Children";
+			}
+
+			oBinding = oModel.bindList(sPath);
+			return this._createFile(oBinding, mCloudFileInfo);
+		}.bind(this)).then(function(sUrl) {
+			if (sUrl) {
+				openWindow(sUrl);
+			}
+		});
+	};
+
+	/**
+	 * Creates a new file via the <code>ODataListBinding</code> based
+	 * on the FileShareItem representation.
+	 *
+	 * @param {sap.ui.model.odata.v4.ODataListBinding} oBinding ListBinding that is bound to the desired folder
+	 * @param {object} mCloudFileInfo FileShareItem representation of the file
+	 * @returns {Promise} Promise that resolves with a Link to the created file
+	 */
+	ExportHandler.prototype._createFile = function(oBinding, mCloudFileInfo) {
+		return new Promise(function(fnResolve, fnReject) {
+			function fnCreateCompleted(oEvent) {
+				var bSuccess, oContext;
+
+				bSuccess = oEvent.getParameter('success');
+				oContext = oEvent.getParameter('context');
+
+				if (bSuccess) {
+					oBinding.detachCreateCompleted(fnCreateCompleted);
+					fnResolve(oContext.getObject()['FileShareItemContentLink']);
+				} else {
+					oContext.destroy();
+					fnReject();
+				}
+			}
+
+			oBinding.attachCreateCompleted(fnCreateCompleted);
+			oBinding.create(mCloudFileInfo, /* bSkipRefresh */ true);
+		});
+	};
+
+	/**
+	 * Exports the data as defined via parameter.
+	 *
+	 * @param {object} mExportSettings ExportSettings that are used for the export
+	 * @returns {Promise} A Promise that gets resolved after the export process has been finished
+	 *
+	 * @since 1.102
+	 * @public
+	 */
+	ExportHandler.prototype.export = function(mExportSettings) {
+		if (this.bIsDestroyed) {
+			Promise.reject('ExportHandler must not be used after calling #destroy');
+		}
+
+		return this.getExportInstance(mExportSettings).then(function(oExportInstance) {
+			return oExportInstance.build().finally(function() {
+				oExportInstance.destroy();
+			});
+		});
+	};
+
+	/**
+	 * Exports the data as defined by the user. This function
+	 * will show up a export settings dialog where the user
+	 * can define certain settings that influence the output
+	 * of the export functionality.
+	 *
+	 * @param {object} oSettings General export settings containing workbook and dataSource information
+	 * @param {function} [fnResolveColumnLabel] Resolves the label for a particular column that is not directly reflected
+	 * @returns {Promise} A Promise that resolves once the data has been exported
+	 *
+	 * @since 1.102
+	 * @public
+	 */
+	ExportHandler.prototype.exportAs = function(oSettings, fnResolveColumnLabel) {
+		var that = this;
+		var mExportSettings = Object.assign({}, oSettings, this._mDialogSettings);
+		var mUserSettings = {};
+
+		if (this.bIsDestroyed) {
+			return Promise.reject('ExportHandler must not be used after calling #destroy');
+		}
+
+		return this.fetchDataSource().then(function(oDestination) {
+			return ExportUtils.getExportSettingsViaDialog(mExportSettings, that._mCapabilities, !!oDestination);
+		}).then(function(mDialogSettings) {
+
+			/* Cache settings dialog settings */
+			that._mDialogSettings = mDialogSettings;
+
+			/* Merge export settings with user settings from the dialog */
+			Object.assign(mExportSettings, mDialogSettings);
+			ExportUtils.validateFileSettings(mExportSettings);
+
+			mUserSettings.splitCells = mDialogSettings.splitCells;
+			mUserSettings.includeFilterSettings = mDialogSettings.includeFilterSettings;
+
+			/* Split columns if configured */
+			if (mDialogSettings.splitCells) {
+				mExportSettings.workbook.columns = ExportUtils.splitColumns(mExportSettings.workbook.columns, fnResolveColumnLabel);
+			}
+
+			if (mDialogSettings.includeFilterSettings) {
+				return ExportUtils.parseFilterConfiguration(oSettings.dataSource, fnResolveColumnLabel);
+			}
+
+			return Promise.resolve();
+		}).then(function(oFilterConfig) {
+			if (oFilterConfig) {
+				var oContext = mExportSettings.workbook.context;
+
+				if (!oContext) {
+					oContext = mExportSettings.workbook.context = {};
+				}
+
+				oContext.metaSheetName = oFilterConfig.name;
+				oContext.metainfo = Array.isArray(oContext.metainfo) ? oContext.metainfo.push(oFilterConfig) : [oFilterConfig];
+			}
+		}).then(function() {
+			if (mExportSettings.destination === Destination.LOCAL) {
+				return Promise.resolve();
+			}
+
+			return that.fetchDataSource().then(function(oDataSource) {
+				return that.getRemoteFileLocation(oDataSource, mExportSettings.fileName);
+			});
+		}).then(function(mCloudFileInfo) {
+			return that.getExportInstance(mExportSettings, mUserSettings, mCloudFileInfo).then(function(oExportInstance) {
+				return oExportInstance.build().finally(function() {
+					oExportInstance.destroy();
+				});
+			});
+		}).catch(ExportDialog.showErrorMessage);
+	};
+
+	/**
+	 * Returns the <code>ODataModel</code> that is required to
+	 * create or update binding contexts.
+	 *
+	 * @param {object} oDataSource DataSource obtained by the FileShareSupport module
+	 * @returns {sap.ui.model.odata.v4.ODataModel} ODataModel for the FileShareSupport service
+	 */
+	ExportHandler.prototype._getModel = function(oDataSource) {
+		if (!this._oModel) {
+			this._oModel = new ODataModel({
+				serviceUrl: oDataSource.uri,
+				synchronizationMode: 'None',
+				autoExpandSelect: true
+			});
+		}
+
+		return this._oModel;
+	};
+
+	return ExportHandler;
+}, /* bExports */ true);