Doc changes before refactor

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

@@ -4,7 +4,10 @@
 
 - Improved performance of switching schemes
 - Improved performance of computing dock configuration, especially on theme changes.
-- Added modules as an option for platformProvider.interop settings and added interopOverride as a module generation option when calling npm run generate-module e.g. npm run generate-module interopOverride 'my override'. Also added the option of changing the order where the default interop override included with WPS is included (first or last or omit) via platformProvider.interop.defaultBrokerStrategy.
+- Added modules as an option for platformProvider.interop settings and added interopOverride as a module generation option when calling npm run generate-module e.g. npm run generate-module interopOverride 'my override'. Also added the option of changing when/if the Workspace Platform Starter default interop override runs:
+  - after (default) - run the Workspace Platform Starter default broker implementation after your interop override modules (so the default implementation is the base class)
+  - before - run the Workspace Platform Starter default broker implementation before your interop override modules (so your interop overrides are the base class for our default implementation)
+  - never - never use the Workspace Platform Starter default implementation (So you will be responsible for adding full interop broker support through your modules)
 
 ## v17.2.0
 

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

@@ -53,10 +53,12 @@ export async function init(
 		logger.info("Getting interop overrides...");
 
 		if (
-			interopOverrideSettings?.defaultBrokerStrategy === "first" ||
+			interopOverrideSettings?.defaultBrokerStrategy === "after" ||
 			isEmpty(interopOverrideSettings?.defaultBrokerStrategy)
 		) {
-			logger.info("Adding default interop override first");
+			logger.info(
+				"Adding default interop override so it executes after the list of custom interop overrides"
+			);
 			allOverrides.push(await getConstructorOverride(interopOverrideSettings));
 		}
 		for (const interopModule of modules) {
@@ -65,10 +67,13 @@ export async function init(
 			allOverrides.push(interopConstructor);
 			logger.info(`Added interopOverride module: ${interopModule.definition.id}`);
 		}
-		if (interopOverrideSettings?.defaultBrokerStrategy === "last") {
-			logger.info("Adding default interop override last");
+		if (interopOverrideSettings?.defaultBrokerStrategy === "before") {
+			logger.info("Adding default interop override so it runs before the list of custom interop overrides");
 			allOverrides.push(await getConstructorOverride(interopOverrideSettings));
 		}
+		if (interopOverrideSettings?.defaultBrokerStrategy === "never") {
+			logger.info("The default interop override will not be added and will not be executed.");
+		}
 		logger.info("Finished setting up interop overrides.");
 		isInitialized = true;
 	}

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

@@ -38,13 +38,13 @@ export type PlatformInteropOverrideOptions = Omit<PlatformInteropBrokerOptions,
  */
 export interface PlatformInteropBrokerOptions extends ModuleList {
 	/**
-	 * The platform includes a default broker override. The default 'first' is to have our built-in implementation added to the start of the array of overrides (so it will execute last).
-	 * If you wish to have your logic called after the default implementation set this to 'last'.
-	 * If you wish to only have your logic called set this to 'omit'.
-	 * If you wish to have your logic called before the default implementation set this to 'first' or leave it as the default.
-	 * The default is first. Please note that if you omit the default implementation you will need to handle all the logic for the interop broker other than what is provided by OpenFin out of the box.
+	 * The platform includes a default broker override and this setting allows you to control when it is called.
+	 * If you wish to have the default interop override execute after your logic (it is the base) then set this to "after" (the default if not set).
+	 * If you wish to have the default interop override execute before your logic (your modules are the base) then set this to "before".
+	 * If you wish to just use your modules then you can specify "never" and the default interop override will not execute anywhere (Please note this
+	 * will mean you will be responsible for implementing all interop broker logic beyond the base runtime implementation).
 	 */
-	defaultBrokerStrategy?: "first" | "last" | "omit";
+	defaultBrokerStrategy?: "before" | "after" | "never";
 	/**
 	 * Intent Resolver configuration if you wish to support intents. It needs to support the functions required by the
 	 * platform

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

@@ -35,13 +35,13 @@ export type PlatformInteropOverrideOptions = Omit<PlatformInteropBrokerOptions,
  */
 export interface PlatformInteropBrokerOptions extends ModuleList {
 	/**
-	 * The platform includes a default broker override. The default 'first' is to have our built-in implementation added to the start of the array of overrides (so it will execute last).
-	 * If you wish to have your logic called after the default implementation set this to 'last'.
-	 * If you wish to only have your logic called set this to 'omit'.
-	 * If you wish to have your logic called before the default implementation set this to 'first' or leave it as the default.
-	 * The default is first. Please note that if you omit the default implementation you will need to handle all the logic for the interop broker other than what is provided by OpenFin out of the box.
+	 * The platform includes a default broker override and this setting allows you to control when it is called.
+	 * If you wish to have the default interop override execute after your logic (it is the base) then set this to "after" (the default if not set).
+	 * If you wish to have the default interop override execute before your logic (your modules are the base) then set this to "before".
+	 * If you wish to just use your modules then you can specify "never" and the default interop override will not execute anywhere (Please note this
+	 * will mean you will be responsible for implementing all interop broker logic beyond the base runtime implementation).
 	 */
-	defaultBrokerStrategy?: "first" | "last" | "omit";
+	defaultBrokerStrategy?: "before" | "after" | "never";
 	/**
 	 * Intent Resolver configuration if you wish to support intents. It needs to support the functions required by the
 	 * platform

how-to/workspace-platform-starter/docs/how-to-customize-your-interop-broker.md

@@ -0,0 +1,103 @@
+> **_:information_source: OpenFin Workspace:_** [OpenFin Workspace](https://www.openfin.co/workspace/) is a commercial product and this repo is for evaluation purposes (See [LICENSE.MD](../LICENSE.MD)). Use of the OpenFin Container and OpenFin Workspace components is only granted pursuant to a license from OpenFin (see [manifest](../public/manifest.fin.json)). Please [**contact us**](https://www.openfin.co/workspace/poc/) if you would like to request a developer evaluation key or to discuss a production license.
+
+[<- Back to Table Of Contents](../README.md)
+
+# How To Customize Your Interop Broker
+
+Workspace Platform Starter includes a default [interop broker override](../client/src/framework/platform/broker/interop-override.ts) that includes support for FDC3 2.0 and intents as well as context. If has been built to support interop with support for the Platform Apps format used by Workspace Platform Starter (directories can still use the FDC3 1.2 & 2.0 format as these are mapped internally to the PlatformApp format).
+
+OpenFin Workspace 17.4+ lets you specify an array of interop overrides that can be layered on top of each other so that different overrides can add custom behavior.
+
+Workspace Platform Starter 17.4 supports this ability by adding two new settings to the platformProvider.interop settings.
+
+## moduleInheritance
+
+This setting lets you how we should treat the interop overrides defined in the modules array:
+
+- derived (default) - Your interop overrides will be derived from our default interop override and your modules will use our implementation as a base.
+- base - Your interop overrides will be the base class for our default interop override and when we call super we are calling your module implementations.
+- standalone - Your modules do not use our default implementation and will be responsible for InteropBroker functionality (extending from the default InteropBroker provided by the OpenFin Workspace Platform NPM Package)
+
+```json
+"platformProvider": {
+  ...
+  "interop": {
+   "moduleInheritance": "derived"
+  }
+}
+```
+
+## modules
+
+These are interop modules that provide custom interop broker logic. If there are more than one then they will extend each other (the earlier entries will act as the base for subsequent entries). By default the first module (and subsequently the ones that follow) will use our default interop override as a base (this can be configured as described above through the module inheritance).
+
+```json
+"platformProvider": {
+  ...
+  "interop": {
+   "modules": [
+    {
+     "enabled": true,
+     "id": "my-interop-override",
+     "url": "http://localhost:8080/js/modules/interop-override/my-interop-override.bundle.js",
+     "data": {
+      "customSetting": "a custom setting that will be passed to the interop override module for use"
+     }
+    }
+   ]
+  }
+}
+```
+
+- Also added the option of changing when/if the Workspace Platform Starter default interop override runs:
+  - after (default) - run the Workspace Platform Starter default broker implementation after your interop override modules (so the default implementation is the base class)
+  - before - run the Workspace Platform Starter default broker implementation before your interop override modules (so your interop overrides are the base class for our default implementation)
+  - never - never use the Workspace Platform Starter default implementation (So you will be responsible for adding full interop broker support through your modules)
+
+## Analytics Provider
+
+You can configure where analytics should be sent by using our Analytics Provider. You can then specify 1 or more modules (see [how to add a module](./how-to-add-a-module.md)) that will receive the analytic events and any config you specify. We have created a [console analytics module](../client/src/modules/analytics/console/) and configured it in [manifest.fin.json](../public/manifest.fin.json) and [second.manifest.fin.json's settings.json file](../public/settings.json). It isn't configured in our [third.manifest.fin.json](../public/third.manifest.fin.json) to show that this is an optional feature.
+
+```json
+"analyticsProvider": {
+   "modules": [
+    {
+     "enabled": true,
+     "id": "analytics.console",
+     "url": "http://localhost:8080/js/modules/analytics/console.bundle.js",
+     "data": {
+      "eventLogLevel": "info"
+     }
+    }
+   ]
+  }
+```
+
+## Platform Override
+
+We call the analytics provider from the [platform override](../client/src/framework/platform/platform-override.ts) file:
+
+```javascript
+public async handleAnalytics(events: AnalyticsEvent[]) {
+  // we call the analytics provider from here and pass the events generated by the workspace components.
+}
+```
+
+## Generate From Template
+
+You can generate the scaffold for a new module by using the following command line, where "My Analytics" is the name you want to give your module:
+
+```shell
+npm run generate-module analytics "My Analytics"
+```
+
+This will generate the code in the modules/analytics folder, add an entry into webpack to build it, and add it to the manifest so that the module is loaded.
+
+## Source Reference
+
+- [Analytics](../client/src/framework/analytics.ts)
+- [PlatformAnalyticsEvent](../client/src/framework/shapes/analytics-shapes.ts)
+- [Console Analytics Module](../client/src/modules/analytics/console/)
+- [Platform Override](../client/src/framework/platform/platform-override.ts)
+
+[<- Back to Table Of Contents](../README.md)

how-to/workspace-platform-starter/public/manifest.fin.json

@@ -356,7 +356,9 @@
 				},
 				"workspacePlatform": {
 					"pages": [],
-					"title": "Browser Starter",
+					"title": {
+						"type": "view-title"
+					},
 					"favicon": "http://localhost:8080/favicon.ico",
 					"newTabUrl": "http://localhost:8080/common/views/platform/new-tab/new-tab.html",
 					"newPageUrl": "http://localhost:8080/common/views/platform/new-tab/new-tab.html",

how-to/workspace-platform-starter/public/pack.manifest.fin.json

@@ -158,7 +158,8 @@
 							"contexts": ["fdc3.instrument"]
 						}
 					]
-				}
+				},
+				"modules": []
 			}
 		},
 		"appProvider": {
@@ -320,7 +321,9 @@
 				},
 				"workspacePlatform": {
 					"pages": [],
-					"title": "Browser Starter",
+					"title": {
+						"type": "view-title"
+					},
 					"favicon": "http://localhost:8080/favicon.ico"
 				}
 			},

how-to/workspace-platform-starter/public/schemas/settings.schema.json

@@ -3972,11 +3972,11 @@
             "description": "Options for the platform interop broker.",
             "properties": {
                 "defaultBrokerStrategy": {
-                    "description": "The platform includes a default broker override. The default 'first' is to have our built-in implementation added to the start of the array of overrides (so it will execute last).\nIf you wish to have your logic called after the default implementation set this to 'last'.\nIf you wish to only have your logic called set this to 'omit'.\nIf you wish to have your logic called before the default implementation set this to 'first' or leave it as the default.\nThe default is first. Please note that if you omit the default implementation you will need to handle all the logic for the interop broker other than what is provided by OpenFin out of the box.",
+                    "description": "The platform includes a default broker override and this setting allows you to control when it is called.\nIf you wish to have the default interop override execute after your logic (it is the base) then set this to \"after\" (the default if not set).\nIf you wish to have the default interop override execute before your logic (your modules are the base) then set this to \"before\".\nIf you wish to just use your modules then you can specify \"never\" and the default interop override will not execute anywhere (Please note this\nwill mean you will be responsible for implementing all interop broker logic beyond the base runtime implementation).",
                     "enum": [
-                        "first",
-                        "last",
-                        "omit"
+                        "after",
+                        "before",
+                        "never"
                     ],
                     "type": "string"
                 },

how-to/workspace-platform-starter/public/schemas/wps.manifest.schema.json

@@ -3683,8 +3683,8 @@
 			"description": "Options for the platform interop broker.",
 			"properties": {
 				"defaultBrokerStrategy": {
-					"description": "The platform includes a default broker override. The default 'first' is to have our built-in implementation added to the start of the array of overrides (so it will execute last).\nIf you wish to have your logic called after the default implementation set this to 'last'.\nIf you wish to only have your logic called set this to 'omit'.\nIf you wish to have your logic called before the default implementation set this to 'first' or leave it as the default.\nThe default is first. Please note that if you omit the default implementation you will need to handle all the logic for the interop broker other than what is provided by OpenFin out of the box.",
-					"enum": ["first", "last", "omit"],
+					"description": "The platform includes a default broker override and this setting allows you to control when it is called.\nIf you wish to have the default interop override execute after your logic (it is the base) then set this to \"after\" (the default if not set).\nIf you wish to have the default interop override execute before your logic (your modules are the base) then set this to \"before\".\nIf you wish to just use your modules then you can specify \"never\" and the default interop override will not execute anywhere (Please note this\nwill mean you will be responsible for implementing all interop broker logic beyond the base runtime implementation).",
+					"enum": ["after", "before", "never"],
 					"type": "string"
 				},
 				"intentOptions": {

how-to/workspace-platform-starter/public/settings.json

@@ -287,7 +287,9 @@
 			},
 			"workspacePlatform": {
 				"pages": [],
-				"title": "Second Browser Starter",
+				"title": {
+					"type": "view-title"
+				},
 				"newTabUrl": "http://localhost:8080/common/views/platform/new-tab/new-tab.html",
 				"newPageUrl": "http://localhost:8080/common/views/platform/new-tab/new-tab.html"
 			}

how-to/workspace-platform-starter/public/third.manifest.fin.json

@@ -152,7 +152,8 @@
 							"contexts": ["fdc3.instrument"]
 						}
 					]
-				}
+				},
+				"modules": []
 			}
 		},
 		"appProvider": {