@sap-ux/fe-fpm-writer 0.14.3 → 0.15.0

package/dist/controller-extension/index.d.ts

@@ -0,0 +1,14 @@
+import type { Editor } from 'mem-fs-editor';
+import type { ControllerExtension } from './types';
+export declare const UI5_CONTROLLER_EXTENSION_LIST_REPORT = "sap.fe.templates.ListReport.ListReportController";
+export declare const UI5_CONTROLLER_EXTENSION_OBJECT_PAGE = "sap.fe.templates.ObjectPage.ObjectPageController";
+/**
+ * Add a controller extension to an existing UI5 application.
+ *
+ * @param {string} basePath - the base path
+ * @param {ControllerExtension} controllerConfig - the controller extension configuration
+ * @param {Editor} [fs] - the memfs editor instance
+ * @returns {Editor} the updated memfs editor instance
+ */
+export declare function generateControllerExtension(basePath: string, controllerConfig: ControllerExtension, fs?: Editor): Editor;
+//# sourceMappingURL=index.d.ts.map

package/dist/controller-extension/index.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateControllerExtension = exports.UI5_CONTROLLER_EXTENSION_OBJECT_PAGE = exports.UI5_CONTROLLER_EXTENSION_LIST_REPORT = void 0;
+const mem_fs_1 = require("mem-fs");
+const mem_fs_editor_1 = require("mem-fs-editor");
+const path_1 = require("path");
+const ejs_1 = require("ejs");
+const types_1 = require("./types");
+const validate_1 = require("../common/validate");
+const defaults_1 = require("../common/defaults");
+const templates_1 = require("../templates");
+exports.UI5_CONTROLLER_EXTENSION_LIST_REPORT = 'sap.fe.templates.ListReport.ListReportController';
+exports.UI5_CONTROLLER_EXTENSION_OBJECT_PAGE = 'sap.fe.templates.ObjectPage.ObjectPageController';
+const UI5_CONTROLLER_EXTENSIONS = 'sap.ui.controllerExtensions';
+const EXTENSION_PAGE_TYPE_MAP = new Map([
+    [types_1.ControllerExtensionPageType.ListReport, exports.UI5_CONTROLLER_EXTENSION_LIST_REPORT],
+    [types_1.ControllerExtensionPageType.ObjectPage, exports.UI5_CONTROLLER_EXTENSION_OBJECT_PAGE]
+]);
+/**
+ * A function appends passed array of values with new value if value does not exist in array.
+ *
+ * @param values - array of values
+ * @param value - value to append
+ * @returns Array of values
+ */
+function appendUniqueEntryToArray(values, value) {
+    if (!values.includes(value)) {
+        values.push(value);
+    }
+    return values;
+}
+/**
+ * A function returns existing controller extension from manifest for passed extension id.
+ *
+ * @param {Manifest} manifest - manifest
+ * @param {string} extensionId - extension id
+ * @returns {ManifestControllerExtension | undefined} Existing controller extension
+ */
+function getExistingControllerExtension(manifest, extensionId) {
+    var _a, _b, _c;
+    const extensions = (_c = (_b = (_a = manifest['sap.ui5']) === null || _a === void 0 ? void 0 : _a.extends) === null || _b === void 0 ? void 0 : _b.extensions) === null || _c === void 0 ? void 0 : _c[UI5_CONTROLLER_EXTENSIONS];
+    if (extensions === null || extensions === void 0 ? void 0 : extensions.hasOwnProperty(extensionId)) {
+        return extensions[extensionId];
+    }
+    return undefined;
+}
+/**
+ * Method enhances the provided controller extension by handling existing controller extension entry from manifest.
+ * Logic applies following:
+ * 1. Handles public property "overwrite" - if we should append or overwrite existing controller names.
+ * 2. Detects transition from "controllerName" to "controllerNames" when new controller is appended to exiusting entry with property "controllerNames".
+ * 3. Adds new controller entry to "controllerNames" array.
+ *
+ * @param {ManifestControllerExtension} manifestExtension - controller extension from manifest
+ * @param {InternalControllerExtension} config - internal controller extension configuration
+ * @param {string} controllerName - full name of new controller to add or replace/overwrite
+ */
+function handleExistingManifestExtension(manifestExtension, config, controllerName) {
+    if (config.overwrite) {
+        if (manifestExtension.controllerNames) {
+            // Delete "controllerNames" from manifest because it will be overwritten by single controllerName
+            config.deleteProperty = 'controllerNames';
+        }
+        // Do not need append new controller with existing - exit further handling
+        return;
+    }
+    // Append new controller extension with existing controllers
+    if (manifestExtension.controllerName && manifestExtension.controllerName !== config.controllerName) {
+        // Manifest has single controller - transfer it into array
+        config.controllerNames = manifestExtension.controllerNames ? [...manifestExtension.controllerNames] : [];
+        // Check before append
+        appendUniqueEntryToArray(config.controllerNames, manifestExtension.controllerName);
+        appendUniqueEntryToArray(config.controllerNames, controllerName);
+        // Delete "controllerName" from manifest
+        config.deleteProperty = 'controllerName';
+    }
+    else if (manifestExtension.controllerNames && !manifestExtension.controllerNames.includes(controllerName)) {
+        // Manifest has array of controllers - append new entry
+        config.controllerNames = appendUniqueEntryToArray([...manifestExtension.controllerNames], controllerName);
+    }
+}
+/**
+ * Method enhances the provided controller extension configuration with default and additional data.
+ *
+ * @param {string} extensionName - a controller extension configuration object
+ * @returns {ControllerExtensionPageTarget | undefined} Page configuration object if extension name is assigned to supported page type.
+ */
+function resolvePageDataFromExtension(extensionName) {
+    for (const [key, value] of EXTENSION_PAGE_TYPE_MAP) {
+        if (extensionName.startsWith(value)) {
+            return {
+                pageType: key
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * Method enhances the provided controller extension configuration with default and additional data.
+ *
+ * @param {ControllerExtension} data - a controller extension configuration object
+ * @param {string} manifestPath - path to the project's manifest.json
+ * @param {Manifest} manifest - the application manifest
+ * @returns enhanced configuration
+ */
+function enhanceConfig(data, manifestPath, manifest) {
+    // clone input
+    const config = Object.assign({}, data);
+    // Apply default data
+    defaults_1.setCommonDefaults(config, manifestPath, manifest);
+    // Create `controllerName` with full path/namespace
+    config.controllerName = `${config.ns}.${config.name}`;
+    // Resolve controller extension id/key
+    let extensionId;
+    if (typeof config.extension === 'object') {
+        // Use default as List Report
+        config.extension.pageType = config.extension.pageType || types_1.ControllerExtensionPageType.ListReport;
+        const { pageType, pageId } = config.extension;
+        extensionId = EXTENSION_PAGE_TYPE_MAP.get(pageType) || exports.UI5_CONTROLLER_EXTENSION_LIST_REPORT;
+        if (pageId) {
+            // Prepend project id
+            extensionId = `${extensionId}#${manifest['sap.app'].id}::${pageId}`;
+        }
+    }
+    else {
+        // Try to resolve page type from manual extension
+        extensionId = config.extension;
+        config.extension = resolvePageDataFromExtension(config.extension) || config.extension;
+    }
+    config.extensionId = extensionId;
+    // Get existing controller extension entry from manifest
+    const manifestExtension = getExistingControllerExtension(manifest, extensionId);
+    // If controller extension already exists in manifest - append new controller
+    if (manifestExtension) {
+        handleExistingManifestExtension(manifestExtension, config, config.controllerName);
+    }
+    return config;
+}
+/**
+ * A function that transforms JSON object during JSON.stringify call.
+ * Method is used to remove 'controllerName' or 'controllerNames' properties from manifest in case when we have transition from 'controllerName' to 'controllerNames'.
+ *
+ * @param {InternalControllerExtension} config - a controller extension configuration object
+ * @returns Json replacer method
+ */
+function getManifestReplacer(config) {
+    let isRoot = true;
+    const { deleteProperty } = config;
+    if (!deleteProperty) {
+        // No request to delete any property
+        return undefined;
+    }
+    return (key, value) => {
+        // Handle only root - more stable solution instead of checking 'key'
+        if (key === '' && isRoot) {
+            isRoot = false;
+            const extension = getExistingControllerExtension(value, config.extensionId);
+            if (extension) {
+                delete extension[deleteProperty];
+            }
+        }
+        return value;
+    };
+}
+/**
+ * Add a controller extension to an existing UI5 application.
+ *
+ * @param {string} basePath - the base path
+ * @param {ControllerExtension} controllerConfig - the controller extension configuration
+ * @param {Editor} [fs] - the memfs editor instance
+ * @returns {Editor} the updated memfs editor instance
+ */
+function generateControllerExtension(basePath, controllerConfig, fs) {
+    // Validate the base and view paths
+    if (!fs) {
+        fs = mem_fs_editor_1.create(mem_fs_1.create());
+    }
+    validate_1.validateBasePath(basePath, fs);
+    const manifestPath = path_1.join(basePath, 'webapp/manifest.json');
+    const manifest = fs.readJSON(manifestPath);
+    // merge with defaults
+    const internalConfig = enhanceConfig(controllerConfig, manifestPath, manifest);
+    // enhance manifest with view definition
+    const filledTemplate = ejs_1.render(fs.read(templates_1.getTemplatePath('controller-extension/manifest.json')), internalConfig, {});
+    fs.extendJSON(manifestPath, JSON.parse(filledTemplate), getManifestReplacer(internalConfig));
+    // add controller js file
+    const ext = controllerConfig.typescript ? 'ts' : 'js';
+    const viewPath = path_1.join(internalConfig.path, `${internalConfig.name}.controller.${ext}`);
+    if (!fs.exists(viewPath)) {
+        fs.copyTpl(templates_1.getTemplatePath(`controller-extension/Controller.${ext}`), viewPath, internalConfig);
+    }
+    return fs;
+}
+exports.generateControllerExtension = generateControllerExtension;
+//# sourceMappingURL=index.js.map

package/dist/controller-extension/types.d.ts

@@ -0,0 +1,61 @@
+import type { CustomElement, InternalCustomElement } from '../common/types';
+/**
+ * Controller extension's associated page type.
+ *
+ * @enum {string}
+ */
+export declare enum ControllerExtensionPageType {
+    ObjectPage = "ObjectPage",
+    ListReport = "ListReport"
+}
+/**
+ * Target page configuration for controller extension.
+ */
+export interface ControllerExtensionPageTarget {
+    /**
+     * The page type for which controller extension should be triggered.
+     */
+    pageType: ControllerExtensionPageType;
+    /**
+     * The unique page id for which controller extension should be triggered.
+     */
+    pageId?: string;
+}
+/**
+ * Controller extension configuration for the generate function.
+ */
+export interface ControllerExtension extends CustomElement {
+    /**
+     * Property to define extension entry point.
+     * Provide any extension name as string or use page configuration.
+     */
+    extension: ControllerExtensionPageTarget | string;
+    /**
+     * Controls if controller(s) for existing controller extension should be appended or replaced with new controller.
+     */
+    overwrite?: boolean;
+}
+/**
+ * Represents a controller extension configuration in manifest.
+ */
+export interface ManifestControllerExtension {
+    /**
+     * Specifies single controller for controller extension.
+     */
+    controllerName?: string;
+    /**
+     * Specifies multiple controllers for controller extension.
+     */
+    controllerNames?: string[];
+}
+export interface InternalControllerExtension extends ControllerExtension, ManifestControllerExtension, InternalCustomElement {
+    /**
+     * Derived full extension key/id in manifest "sap.ui.controllerExtensions" object.
+     */
+    extensionId: string;
+    /**
+     * Delete property from existing control extension object in manifest.
+     */
+    deleteProperty?: keyof ManifestControllerExtension;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/controller-extension/types.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControllerExtensionPageType = void 0;
+/**
+ * Controller extension's associated page type.
+ *
+ * @enum {string}
+ */
+var ControllerExtensionPageType;
+(function (ControllerExtensionPageType) {
+    ControllerExtensionPageType["ObjectPage"] = "ObjectPage";
+    ControllerExtensionPageType["ListReport"] = "ListReport";
+})(ControllerExtensionPageType = exports.ControllerExtensionPageType || (exports.ControllerExtensionPageType = {}));
+//# sourceMappingURL=types.js.map

package/dist/index.d.ts

@@ -12,4 +12,6 @@ export { enableFPM, FPMConfig } from './app';
 export { validateBasePath, validateVersion } from './common/validate';
 export { BuildingBlockType, FilterBar, Chart, Field, FieldFormatOptions } from './building-block/types';
 export { generateBuildingBlock } from './building-block';
+export { ControllerExtension, ControllerExtensionPageType } from './controller-extension/types';
+export { generateControllerExtension } from './controller-extension';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateBuildingBlock = exports.BuildingBlockType = exports.validateVersion = exports.validateBasePath = exports.enableFPM = exports.generateCustomView = exports.generateCustomSection = exports.generateCustomColumn = exports.generateCustomAction = exports.TargetControl = exports.generateListReport = exports.generateObjectPage = exports.generateCustomPage = void 0;
+exports.generateControllerExtension = exports.ControllerExtensionPageType = exports.generateBuildingBlock = exports.BuildingBlockType = exports.validateVersion = exports.validateBasePath = exports.enableFPM = exports.generateCustomView = exports.generateCustomSection = exports.generateCustomColumn = exports.generateCustomAction = exports.TargetControl = exports.generateListReport = exports.generateObjectPage = exports.generateCustomPage = void 0;
 var page_1 = require("./page");
 Object.defineProperty(exports, "generateCustomPage", { enumerable: true, get: function () { return page_1.generateCustomPage; } });
 Object.defineProperty(exports, "generateObjectPage", { enumerable: true, get: function () { return page_1.generateObjectPage; } });
@@ -24,4 +24,8 @@ var types_2 = require("./building-block/types");
 Object.defineProperty(exports, "BuildingBlockType", { enumerable: true, get: function () { return types_2.BuildingBlockType; } });
 var building_block_1 = require("./building-block");
 Object.defineProperty(exports, "generateBuildingBlock", { enumerable: true, get: function () { return building_block_1.generateBuildingBlock; } });
+var types_3 = require("./controller-extension/types");
+Object.defineProperty(exports, "ControllerExtensionPageType", { enumerable: true, get: function () { return types_3.ControllerExtensionPageType; } });
+var controller_extension_1 = require("./controller-extension");
+Object.defineProperty(exports, "generateControllerExtension", { enumerable: true, get: function () { return controller_extension_1.generateControllerExtension; } });
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sap-ux/fe-fpm-writer",
   "description": "SAP Fiori elements flexible programming model writer",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/SAP/open-ux-tools.git",

package/templates/controller-extension/Controller.js

@@ -0,0 +1,18 @@
+sap.ui.define(['sap/ui/core/mvc/ControllerExtension'], function (ControllerExtension) {
+	'use strict';
+
+	return ControllerExtension.extend('<%- ns %>.<%- name %>', {
+		// this section allows to extend lifecycle hooks or hooks provided by Fiori elements
+		override: {
+			/**
+             * Called when a controller is instantiated and its View controls (if available) are already created.
+             * Can be used to modify the View before it is displayed, to bind event handlers and do other one-time initialization.
+             * @memberOf <%- ns %>.<%- name %>
+             */
+			onInit: function () {
+				// you can access the Fiori elements extensionAPI via this.base.getExtensionAPI
+				var oModel = this.base.getExtensionAPI().getModel();
+			}
+		}
+	});
+});

package/templates/controller-extension/Controller.ts

@@ -0,0 +1,26 @@
+import ControllerExtension from 'sap/ui/core/mvc/ControllerExtension';
+import ExtensionAPI from 'sap/fe/<%- typeof extension === "object" ? `templates/${extension.pageType}` : "core" -%>/ExtensionAPI';
+
+/**
+ * Definition of the override interface as workaround until https://github.com/SAP/ui5-typescript/issues/332 is fixed.
+ */
+interface ExtensionOverride {
+	base: {
+		getExtensionAPI(): ExtensionAPI;
+	}
+}
+
+export default ControllerExtension.extend('<%- ns %>.<%- name %>', {
+	// this section allows to extend lifecycle hooks or hooks provided by Fiori elements
+	override: {
+		/**
+		 * Called when a controller is instantiated and its View controls (if available) are already created.
+		 * Can be used to modify the View before it is displayed, to bind event handlers and do other one-time initialization.
+		 * @memberOf <%- ns %>.<%- name %>
+		 */
+		onInit(this: ExtensionOverride) {
+			// you can access the Fiori elements extensionAPI via this.base.getExtensionAPI
+			const model = this.base.getExtensionAPI().getModel();
+		}
+	}
+});

package/templates/controller-extension/manifest.json

@@ -0,0 +1,14 @@
+{
+    "sap.ui5": {
+        "extends": {
+            "extensions": {
+                "sap.ui.controllerExtensions": {
+                    "<%- extensionId -%>": {<%if (typeof controllerNames !== 'undefined') {%>
+                        "controllerNames": <%- JSON.stringify(controllerNames) %><% } else {%>
+                        "controllerName": "<%- controllerName %>"<% } %>
+                    }
+                }
+            }
+        }
+    }
+}