Dev/john/native preferences

how-to/workspace-platform-starter/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## v16
 
+- Improved launchPreference so that now args for a native app (app asset or external) can be specified via launchPreference. Launch preference can also be configured to allow args to be specified dynamically when the launch request is made.
 - Improved launchPreference so additional options such as url, interop, customData can be specified. Modules can now pass a launchPreference when launching an app by appId. They can see if the app supports being updated by getting the app by id and checking for the updatable setting under launchPreference.options. Only inline-view/view and inline-window/window support updatable launch preferences. Please see [how to define app launch preference](./docs/how-to-define-app-launch-preference.md).
 - Added support for Snap, enable by setting `customSettings.snapProvider.enabled` to true. Configure the `customSettings.snapProvider.serverAssetInfo` to point to the `SNAP_ASSET_URL`. Enable the Snap debugging window by setting `customSettings.snapProvider.showDebugWindow` to true.
 - Added new module type `content-creation`, these modules can be used to define content creation rules and handle the associated events. Modules are added in `customSettings.contentCreationProvider` section in manifest.

how-to/workspace-platform-starter/client/src/framework/launch.ts

@@ -54,15 +54,15 @@ export async function launch(
 		switch (app.manifestType) {
 			case MANIFEST_TYPES.External.id:
 			case MANIFEST_TYPES.InlineExternal.id: {
-				const platformIdentity = await launchExternal(app);
+				const platformIdentity = await launchExternal(app, undefined, launchPreference);
 				if (platformIdentity) {
 					platformAppIdentities.push(platformIdentity);
 				}
 				break;
 			}
 			case MANIFEST_TYPES.Appasset.id:
 			case MANIFEST_TYPES.InlineAppAsset.id: {
-				const platformIdentity = await launchAppAsset(app);
+				const platformIdentity = await launchAppAsset(app, undefined, launchPreference);
 				if (platformIdentity) {
 					platformAppIdentities.push(platformIdentity);
 				}
@@ -846,11 +846,13 @@ async function launchSnapshot(snapshotApp: PlatformApp): Promise<PlatformAppIden
  * Launch an app asset for the platform app.
  * @param appAssetApp The app to launch app asset view for.
  * @param instanceId Provide an instance id for the app being launched.
+ * @param launchPreference Optional custom launch preferences
  * @returns The identities of the snapshot parts launched.
  */
 export async function launchAppAsset(
 	appAssetApp: PlatformApp,
-	instanceId?: string
+	instanceId?: string,
+	launchPreference?: UpdatableLaunchPreference
 ): Promise<PlatformAppIdentifier | undefined> {
 	const options: OpenFin.ExternalProcessRequestType = {};
 	logger.info(`Request to launch app asset app of type ${appAssetApp.manifestType}`);
@@ -881,7 +883,7 @@ export async function launchAppAsset(
 	}
 	try {
 		logger.info(`Launching app asset with appId: ${appAssetApp.appId} with the following options:`, options);
-		const identity = await launchExternalProcess(appAssetApp, options, instanceId);
+		const identity = await launchExternalProcess(appAssetApp, options, instanceId, launchPreference);
 		logger.info(
 			`External app with appId: ${appAssetApp.appId} launched with the following identity`,
 			identity
@@ -896,11 +898,13 @@ export async function launchAppAsset(
  * Launch an external for the platform app.
  * @param externalApp The app to launch external view for.
  * @param instanceId Provide an instance id for the app being launched.
+ * @param launchPreference Optional custom launch preferences
  * @returns The identities of the app parts launched.
  */
 export async function launchExternal(
 	externalApp: PlatformApp,
-	instanceId?: string
+	instanceId?: string,
+	launchPreference?: UpdatableLaunchPreference
 ): Promise<PlatformAppIdentifier | undefined> {
 	let options: OpenFin.ExternalProcessRequestType = {};
 	logger.info(`Request to external app of type ${externalApp.manifestType}`);
@@ -922,7 +926,7 @@ export async function launchExternal(
 			`Launching external app asset with appId: ${externalApp.appId} with the following options:`,
 			options
 		);
-		const identity = await launchExternalProcess(externalApp, options, instanceId);
+		const identity = await launchExternalProcess(externalApp, options, instanceId, launchPreference);
 		logger.info(
 			`External app with appId: ${externalApp.appId} launched with the following identity`,
 			identity
@@ -938,18 +942,47 @@ export async function launchExternal(
  * @param app The app being launched.
  * @param options The launch options.
  * @param instanceId Provide an instance id for the app being launched.
+ * @param launchPreference Optional custom launch preferences
  * @returns The identity of the process.
  */
 async function launchExternalProcess(
 	app: PlatformApp,
 	options: OpenFin.ExternalProcessRequestType,
-	instanceId?: string
+	instanceId?: string,
+	launchPreference?: UpdatableLaunchPreference
 ): Promise<PlatformAppIdentifier> {
 	const nativeOptions = app.launchPreference?.options as NativeLaunchOptions;
 
 	const hasPath = isStringValue(options.path);
 
 	let identity: PlatformAppIdentifier | undefined;
+
+	let args: string[] | undefined;
+
+	if (app.launchPreference?.options?.type === "native") {
+		if (
+			launchPreference?.options?.type === "native" &&
+			Array.isArray(launchPreference.options.updatable) &&
+			launchPreference.options.updatable.length > 0
+		) {
+			for (const option of launchPreference.options.updatable) {
+				if (option.name === "args" && Array.isArray(launchPreference.options.native?.args)) {
+					args = launchPreference.options.native?.args;
+					logger.debug(`Using passed launch preference for the args for app ${app.appId}`, args);
+				}
+			}
+		}
+		if (isEmpty(args) && Array.isArray(app.launchPreference?.options?.native?.args)) {
+			args = app.launchPreference?.options?.native?.args;
+			logger.debug(`Using app definition based args for app ${app.appId}`, args);
+		}
+	}
+	if (isEmpty(args) && isStringValue(options.arguments)) {
+		args = [options.arguments];
+	} else {
+		args = [];
+	}
+
 	if (
 		snapProvider.isEnabled() &&
 		nativeOptions?.type === "native" &&
@@ -973,11 +1006,6 @@ async function launchExternalProcess(
 				instanceId = app.instanceMode === "single" ? app.appId : randomUUID();
 			}
 
-			let args = nativeOptions.snap?.args;
-			if (!isStringValue(args) && isStringValue(options.arguments)) {
-				args = [options.arguments];
-			}
-
 			const launchIdentity = await snapProvider.launchApp(
 				path,
 				args,
@@ -1001,7 +1029,9 @@ async function launchExternalProcess(
 	}
 
 	if (isEmpty(identity)) {
-		const launchIdentity = await fin.System.launchExternalProcess(options);
+		const clonedOptions = objectClone(options);
+		clonedOptions.arguments = args.join(" ");
+		const launchIdentity = await fin.System.launchExternalProcess(clonedOptions);
 		identity = { ...launchIdentity, appId: app.appId };
 	}
 

how-to/workspace-platform-starter/client/src/framework/shapes/app-shapes.ts

@@ -163,14 +163,24 @@ export interface Preference<T = unknown> {
 	/**
 	 * What setting is updatable?
 	 */
-	name: ViewPreferenceName | WebPreferenceName;
+	name: ViewPreferenceName | WebPreferenceName | NativePreferenceName;
 
 	/**
 	 * Is there a constraint that the platform can apply?
 	 */
 	constraint?: T;
 }
 
+/**
+ * Which Launch Options are updatable and are there any constraints
+ */
+export interface NativePreference<T = never> extends Preference<T> {
+	/**
+	 * What setting is updatable?
+	 */
+	name: NativePreferenceName;
+}
+
 /**
  * Which Launch Options are updatable and are there any constraints
  */
@@ -191,6 +201,11 @@ export interface ViewPreferenceUrl extends ViewPreference<PreferenceConstraintUr
 	name: "url" | "host-options";
 }
 
+/**
+ * A list of native related settings that can be updated.
+ */
+export type NativePreferenceName = "args";
+
 /**
  * A list of web related settings that can be updated.
  */
@@ -218,6 +233,22 @@ export interface NativeLaunchOptions extends LaunchOptions {
 	 * If specified it indicates the native app should be included when snapping.
 	 */
 	snap?: SnapLaunchOptions;
+
+	/**
+	 * Launch Preferences related to native apps
+	 */
+	native?: {
+		/**
+		 * Arguments are set as an array for compatibility with appAssets, launchExternalProcess and Snap.
+		 */
+		args?: string[];
+	};
+
+	/**
+	 * What can be specified when launching a native app. This is an array of named types to reflect the properties you are happy to be specified.
+	 * By default nothing can be set outside of the app definition when launching the app.
+	 */
+	updatable?: NativePreference[];
 }
 
 /**
@@ -267,12 +298,6 @@ export interface HostLaunchOptions {
  * Additional options that apply to the app when used in a snap context
  */
 export interface SnapLaunchOptions {
-	/**
-	 * Snap requires args as a string array, not a single string like in app assets.
-	 * So we provide the ability to include them here.
-	 */
-	args?: string[];
-
 	/**
 	 * The strategy for launching and locating the application.
 	 */

how-to/workspace-platform-starter/client/types/module/shapes/app-shapes.d.ts

@@ -145,12 +145,21 @@ export interface Preference<T = unknown> {
 	/**
 	 * What setting is updatable?
 	 */
-	name: ViewPreferenceName | WebPreferenceName;
+	name: ViewPreferenceName | WebPreferenceName | NativePreferenceName;
 	/**
 	 * Is there a constraint that the platform can apply?
 	 */
 	constraint?: T;
 }
+/**
+ * Which Launch Options are updatable and are there any constraints
+ */
+export interface NativePreference<T = never> extends Preference<T> {
+	/**
+	 * What setting is updatable?
+	 */
+	name: NativePreferenceName;
+}
 /**
  * Which Launch Options are updatable and are there any constraints
  */
@@ -169,6 +178,10 @@ export interface ViewPreferenceUrl extends ViewPreference<PreferenceConstraintUr
 	 */
 	name: "url" | "host-options";
 }
+/**
+ * A list of native related settings that can be updated.
+ */
+export type NativePreferenceName = "args";
 /**
  * A list of web related settings that can be updated.
  */
@@ -193,6 +206,20 @@ export interface NativeLaunchOptions extends LaunchOptions {
 	 * If specified it indicates the native app should be included when snapping.
 	 */
 	snap?: SnapLaunchOptions;
+	/**
+	 * Launch Preferences related to native apps
+	 */
+	native?: {
+		/**
+		 * Arguments are set as an array for compatibility with appAssets, launchExternalProcess and Snap.
+		 */
+		args?: string[];
+	};
+	/**
+	 * What can be specified when launching a native app. This is an array of named types to reflect the properties you are happy to be specified.
+	 * By default nothing can be set outside of the app definition when launching the app.
+	 */
+	updatable?: NativePreference[];
 }
 /**
  * Additional options that apply to the host of the content
@@ -233,11 +260,6 @@ export interface HostLaunchOptions {
  * Additional options that apply to the app when used in a snap context
  */
 export interface SnapLaunchOptions {
-	/**
-	 * Snap requires args as a string array, not a single string like in app assets.
-	 * So we provide the ability to include them here.
-	 */
-	args?: string[];
 	/**
 	 * The strategy for launching and locating the application.
 	 */

how-to/workspace-platform-starter/public/schemas/fdc3v1.2-appd.schema.json

@@ -315,6 +315,20 @@
 			"additionalProperties": false,
 			"description": "Additional options that apply to a native app",
 			"properties": {
+				"native": {
+					"additionalProperties": false,
+					"description": "Launch Preferences related to native apps",
+					"properties": {
+						"args": {
+							"description": "Arguments are set as an array for compatibility with appAssets, launchExternalProcess and Snap.",
+							"items": {
+								"type": "string"
+							},
+							"type": "array"
+						}
+					},
+					"type": "object"
+				},
 				"snap": {
 					"$ref": "#/definitions/SnapLaunchOptions",
 					"description": "If specified it indicates the native app should be included when snapping."
@@ -323,11 +337,35 @@
 					"const": "native",
 					"description": "Native options type",
 					"type": "string"
+				},
+				"updatable": {
+					"description": "What can be specified when launching a native app. This is an array of named types to reflect the properties you are happy to be specified.\nBy default nothing can be set outside of the app definition when launching the app.",
+					"items": {
+						"$ref": "#/definitions/NativePreference<never>"
+					},
+					"type": "array"
 				}
 			},
 			"required": ["type"],
 			"type": "object"
 		},
+		"NativePreference<never>": {
+			"additionalProperties": false,
+			"description": "Which Launch Options are updatable and are there any constraints",
+			"properties": {
+				"name": {
+					"$ref": "#/definitions/NativePreferenceName",
+					"description": "What setting is updatable?"
+				}
+			},
+			"required": ["name"],
+			"type": "object"
+		},
+		"NativePreferenceName": {
+			"const": "args",
+			"description": "A list of native related settings that can be updated.",
+			"type": "string"
+		},
 		"Partial": {
 			"$ref": "#/definitions/__type"
 		},
@@ -343,13 +381,6 @@
 			"additionalProperties": false,
 			"description": "Additional options that apply to the app when used in a snap context",
 			"properties": {
-				"args": {
-					"description": "Snap requires args as a string array, not a single string like in app assets.\nSo we provide the ability to include them here.",
-					"items": {
-						"type": "string"
-					},
-					"type": "array"
-				},
 				"strategy": {
 					"$ref": "#/definitions/LaunchStrategy",
 					"description": "The strategy for launching and locating the application."