@openfin/core 33.76.27 → 33.76.36

package/src/api/platform/Factory.js

@@ -3,57 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const base_1 = require("../base");
 const Instance_1 = require("./Instance");
 const index_1 = require("./layout/index");
-/**
- * @PORTED
- * InitPlatformOptions interface
- * @typedef { object } InitPlatformOptions
- * @property { OverrideCallback } [overrideCallback] a callback function that can be used to extend or replace default Provider behavior.
- */
-/**
- * @PORTED
- * @typedef { same | different } ProcessAffinityStrategy
- * @summary Strategy to place views that share a domain into different process affinities or the same process affinity.
- * @property { string } same views in the same domain will have the same process affinity.
- * @property { string } different views in the same domain will have different process affinities.
- */
-/**
- * @PORTED
- * @typedef { object } PlatformOptions
- * @summary The options object required by {@link Platform#start Platform.start}
- * Any {@link ApplicationOptions Application option} is also a valid platform option
- * @property {Array.<Object>} [commands] Configuration for keyboard commands.
- * For details and usage, see [Using Keyboard Commands]{@link https://developers.openfin.co/docs/platform-api#section-5-3-using-keyboard-commands}.
- * @property {DefaultWindowOptions} [defaultWindowOptions] Default window options apply to all platform windows.
- * @property {View~options} [defaultViewOptions] Default view options apply to all platform views.
- * @property {ProcessAffinityStrategy} [viewProcessAffinityStrategy] 'same' | 'different'.
- */
-/**
- * @PORTED
- * @typedef { object } DefaultWindowOptions
- * @summary Default window options apply to all platform windows.
- * Any {@link Window~options Window option} is also a valid Default Window option
- * used by default in any window that is created in the current platform's scope.
- * Individual window options will override these defaults.
- * @property {string} [stylesheetUrl]
- * Specify a path of a custom CSS file to be injected to all of the platform's windows.
- * _note_: this option is only applied to windows that use the Default OpenFin Window.
- * Windows with a specified url (Custom Windows) will not be affected by this option.
- */
-/**
- * @DELETED
- * Snapshot interface
- * @typedef { object } Snapshot
- * @property { WindowOption[] } windows The array of window options objects
- */
-/**
- * @lends Platform
- */
 class PlatformModule extends base_1.Base {
+    /**
+     * @internal
+     */
     constructor(wire, channel) {
         super(wire);
         this._channel = channel;
         /**
-         * @namespace
+         *
          * @desc Layouts give app providers the ability to embed multiple views in a single window.  The Layout namespace
          * enables the initialization and manipulation of a window's Layout.  A Layout will
          * <a href="tutorial-Layout.DOMEvents.html">emit events locally</a> on the DOM element representing the layout-container.
@@ -62,10 +20,53 @@ class PlatformModule extends base_1.Base {
     }
     /**
      * Initializes a Platform. Must be called from the Provider when using a custom provider.
-     * @param { InitPlatformOptions } [options] - platform options including a callback function that can be used to extend or replace
+     * @param options - platform options including a callback function that can be used to extend or replace
      * default Provider behavior.
-     * @return {Promise.<void>}
-     * @tutorial Platform.init
+     *
+     * @remarks Must be called from the Provider when using a custom provider.
+     *
+     * @example
+     *
+     * ```js
+     * // From Provider context
+     * await fin.Platform.init();
+     * // Platform API is now hooked up and windows contained in the manifest snapshot are open.
+     * ```
+     *
+     * `Platform.init` accepts an options object that can contain a callback function which can be used to extend or
+     * replace default Provider behavior. As an argument, this function will receive the `Provider` class, which is
+     * used to handle Platform actions. The function must return an object with methods to handle Platform API actions.
+     * The recommended approach is to extend the `Provider` class, overriding the methods you wish to alter, and return an
+     * instance of your subclass:
+     *
+     * ```js
+     * const overrideCallback = async (PlatformProvider) => {
+     *     // Actions can be performed before initialization.
+     *     // e.g. we might authenticate a user, set up a Channel, etc before initializing the Platform.
+     *     const { manifestUrl } = await fin.Application.getCurrentSync().getInfo();
+     *
+     *     // Extend or replace default PlatformProvider behavior by extending the PlatformProvider class.
+     *     class MyOverride extends PlatformProvider {
+     *         // Default behavior can be changed by implementing methods with the same names as those used by the default PlatformProvider.
+     *         async getSnapshot() {
+     *             // Since we are extending the class, we can call `super` methods to access default behavior.
+     *             const snapshot = await super.getSnapshot();
+     *             // But we can modify return values.
+     *             return { ...snapshot, answer: 42, manifestUrl };
+     *         }
+     *         async replaceLayout({ opts, target }) {
+     *             // To disable an API method, overwrite with a noop function.
+     *             return;
+     *         }
+     *     }
+     *     // Return instance with methods to be consumed by Platform.
+     *     // The returned object must implement all methods of the PlatformProvider class.
+     *     // By extending the class, we can simply inherit methods we do not wish to alter.
+     *     return new MyOverride();
+     * };
+     *
+     * fin.Platform.init({overrideCallback});
+     * ```
      * @experimental
      * @static
      */
@@ -74,9 +75,15 @@ class PlatformModule extends base_1.Base {
     }
     /**
      * Asynchronously returns a Platform object that represents an existing platform.
-     * @param { Identity } identity
-     * @return {Promise.<Platform>}
-     * @tutorial Platform.wrap
+     * @param identity
+     *
+     * @example
+     * ```js
+     * const { identity } = fin.me;
+     * const platform = await fin.Platform.wrap(identity);
+     * // Use wrapped instance to control layout, e.g.:
+     * const snapshot = await platform.getSnapshot();
+     * ```
      * @static
      */
     async wrap(identity) {
@@ -87,9 +94,15 @@ class PlatformModule extends base_1.Base {
     }
     /**
      * Synchronously returns a Platform object that represents an existing platform.
-     * @param { Identity } identity
-     * @return {Platform}
-     * @tutorial Platform.wrapSync
+     * @param identity
+     *
+     * @example
+     * ```js
+     * const { identity } = fin.me;
+     * const platform = fin.Platform.wrapSync(identity);
+     * // Use wrapped instance to control layout, e.g.:
+     * const snapshot = await platform.getSnapshot();
+     * ```
      * @static
      */
     wrapSync(identity) {
@@ -100,8 +113,13 @@ class PlatformModule extends base_1.Base {
     }
     /**
      * Asynchronously returns a Platform object that represents the current platform.
-     * @return {Promise.<Platform>}
-     * @tutorial Platform.getCurrent
+     *
+     * @example
+     * ```js
+     * const platform = await fin.Platform.getCurrent();
+     * // Use wrapped instance to control layout, e.g.:
+     * const snapshot = await platform.getSnapshot();
+     * ```
      * @static
      */
     async getCurrent() {
@@ -112,8 +130,13 @@ class PlatformModule extends base_1.Base {
     }
     /**
      * Synchronously returns a Platform object that represents the current platform.
-     * @return {Platform}
-     * @tutorial Platform.getCurrentSync
+     *
+     * @example
+     * ```js
+     * const platform = fin.Platform.getCurrentSync();
+     * // Use wrapped instance to control layout, e.g.:
+     * const snapshot = await platform.getSnapshot();
+     * ```
      * @static
      */
     getCurrentSync() {
@@ -125,9 +148,27 @@ class PlatformModule extends base_1.Base {
     /**
      * Creates and starts a Platform and returns a wrapped and running Platform instance. The wrapped Platform methods can
      * be used to launch content into the platform.  Promise will reject if the platform is already running.
-     * @param { PlatformOptions } platformOptions
-     * @return {Promise.<Platform>}
-     * @tutorial Platform.start
+     * @param platformOptions
+     *
+     * @example
+     * ```js
+     * try {
+     *     const platform = await fin.Platform.start({
+     *         uuid: 'platform-1',
+     *         autoShow: false,
+     *         defaultWindowOptions: {
+     *             stylesheetUrl: 'css-sheet-url',
+     *             cornerRounding: {
+     *                 height: 10,
+     *                 width: 10
+     *             }
+     *         }
+     *     });
+     *     console.log('Platform is running', platform);
+     * } catch(e) {
+     *     console.error(e);
+     * }
+     * ```
      * @static
      */
     start(platformOptions) {
@@ -154,10 +195,25 @@ class PlatformModule extends base_1.Base {
     /**
      * Retrieves platforms's manifest and returns a wrapped and running Platform.  If there is a snapshot in the manifest,
      * it will be launched into the platform.
-     * @param {string} manifestUrl - The URL of platform's manifest.
-     * @param {RvmLaunchOptions} [opts] - Parameters that the RVM will use.
-     * @return {Promise.<Platform>}
-     * @tutorial Platform.startFromManifest
+     * @param manifestUrl - The URL of platform's manifest.
+     * @param opts - Parameters that the RVM will use.
+     *
+     * @example
+     * ```js
+     * try {
+     *     const platform = await fin.Platform.startFromManifest('https://openfin.github.io/golden-prototype/public.json');
+     *     console.log('Platform is running, wrapped platform: ', platform);
+     * } catch(e) {
+     *     console.error(e);
+     * }
+     * // For a local manifest file:
+     * try {
+     *     const platform = await fin.Platform.startFromManifest('file:///C:/somefolder/app.json');
+     *     console.log('Platform is running, wrapped platform: ', platform);
+     * } catch(e) {
+     *     console.error(e);
+     * }
+     * ```
      * @static
      */
     startFromManifest(manifestUrl, opts) {