Interface PlatformProvider

Handles requests to apply a snapshot to the current Platform.

Remarks

Allows overriding a platform's default snapshot behavior. All calls to Platform.applySnapshot will pass through the override.

Example

const overrideCallback = (Provider) => {
    class Override extends Provider {
        async applySnapshot(payload, callerIdentity) {
            const { snapshot, options } = payload;
            // Perhaps in our platform, we wish to always use the closeExistingWindows option
            return super.applySnapshot(
                { snapshot, options: { ...options, closeExistingWindows: true }},
                callerIdentity
            );
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });
Copy

It takes in an array of Views and returns an object specifying which of them are trying to prevent an unload and which are not.

Closes a view

Remarks

Allows overriding a platform's default view closing behavior. All calls to Platform.closeView will pass through the override.

Example

const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
        async closeView(payload, callerIdentity) {
            const { view } = payload;
            // Perhaps in our platform, we want to take a snapshot and save it somewhere before closing certain views.
            if (view.name === 'my-special-view') {
                const snapshot = await fin.Platform.getCurrentSync().getSnapshot();
                await saveSnapshot(snapshot);
            }
            return super.closeView(options, callerIdentity);
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });

async function saveSnapshot(snapshot) {
    // Save the snapshot in localstorage, send to a server, etc.
}
Copy

Closes a Window. By default it will fire any before unload handler set by a View in the Window. This can be disabled by setting skipBeforeUnload in the options object of the payload. This method is called by Platform.closeWindow.

Remarks

This method calls a number of Platform Provider methods:

• getViewsForWindowClose
• checkViewsForPreventUnload
• getUserDecisionForBeforeUnload
• handleViewsAndWindowClose

Example

const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
        async closeWindow(payload, callerIdentity) {
            const { windowId: { uuid, name }, options: { skipBeforeUnload } } = payload;
            console.log(`${uuid}/${name} is closing and skipBeforeUnload is set to: ${skipBeforeUnload}`);
            return super.closeWindow(payload, callerIdentity);
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });
Copy

Creates a new view and attaches it to a specified target window.

Handles requests to create a window in the current platform.

Remarks

If createWindow was called as part of applying a snapshot or creating a view without a target window, identity will be undefined.

Allows overriding a platform's default window creation behavior. All calls to Platform.createWindow will pass through the override.

Example

const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
        async createWindow(options, callerIdentity) {
            if (options.reason === 'tearout') {
                // Perhaps in our platform, we want tearout windows to have a certain initial context value
                const customContext = {
                    security: 'STOCK',
                    currentView: 'detailed'
                }
                return super.createWindow({ ...options, customContext }, callerIdentity);
            }
            // default behavior for all other creation reasons
            return super.createWindow(options, callerIdentity);
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });
Copy

Handles requests to fetch manifests in the current platform.

Remarks

If fetchManifest was called internally, callerIdentity will be the provider's identity.

Allows overriding a platform's default behavior when fetching manifests. Overwriting this call will change how Platform.launchContentManifest and fins links fetch manifests. All calls to Platform.fetchManifest will also pass through the override.

Example

const overrideCallback = (Provider) => {
    class Override extends Provider {
        async fetchManifest(payload, callerIdentity) {
            const { manifestUrl } = payload;

            // I want to fetch certain URLs from the platform provider so that renderer-side cookies will be sent
            if (manifestUrl === 'https://www.my-internal-manifest.com') {
                const manifest = await fetch(manifestUrl);
                return manifest.json();
            }

            // Any requests that might be cross-origin should still be sent from the browser process
            return super.fetchManifest(payload);
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });
Copy

Gets the current state of windows and their views and returns a snapshot object containing that info.

Remarks

Allows overriding a platform's default snapshot behavior. All calls to Platform.getSnapshot will pass through the override.

Example

const overrideCallback = (PlatformProvider) => {
    // Extend default behavior
    class MyOverride extends PlatformProvider {
        async getSnapshot(payload, callerIdentity) {
            // Call super to access vanilla platform behavior
            const snapshot = await super.getSnapshot();
            // Perform any additional logic needed
            const modifiedSnapshot = { ...snapshot, answer: 42 }
            await saveSnapshotToServer(modifiedSnapshot);
            return modifiedSnapshot;
        }
    }
    // Return instance with methods to be consumed by Platform
    return new MyOverride();
};
fin.Platform.init({ overrideCallback });

async function saveSnapshotToServer(snapshot) {
    // Send a snapshot to the server, store it locally somewhere, etc.
}
Copy

Handle the decision of whether a Window or specific View should close when trying to prevent an unload. This is meant to be overridden. Called in PlatformProvider.closeWindow. Normally you would use this method to show a dialog indicating that there are Views that are trying to prevent an unload. By default it will always return all Views passed into it as meaning to close.

Example

const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
        async getUserDecisionForBeforeUnload(payload, callerIdentity) {
            const { windowShouldClose, viewsPreventingUnload, viewsNotPreventingUnload, windowId, closeType } = payload;

            // launch dialog and wait for user response
            const continueWithClose = await showDialog(viewsPreventingUnload, windowId, closeType);

            if (continueWithClose) {
                return { windowShouldClose, viewsToClose: [...viewsNotPreventingUnload, ...viewsPreventingUnload] };
            } else {
                return { windowShouldClose: false, viewsToClose: [] };
            }
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });

async function showDialog(viewsPreventingUnload, windowId, closeType) {
    // Show a dialog and await for user response
}
Copy

Gets all the Views attached to a Window that should close along with it. This is meant to be overridable in the case where you want to return other Views that may not be attached to the Window that is closing.

Handles requests to get a window's context. target may be a window or a view. If it is a window, that window's customContext will be returned. If it is a view, the customContext of that view's current host window will be returned.

Remarks

Allows overriding a platform's default getWindowContext behavior. All calls to Platform.getWindowContext will pass through the override.

Example

const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
        async getWindowContext(payload, callerIdentity) {
            // Perhaps in our platform, we wish to make window context available only to views from a given domain.
            const { entityType } = callerIdentity;
            if (entityType === 'view') {
                const { url } = await fin.View.wrapSync(callerIdentity).getInfo();
                if (!url.startsWith('https://my.trusted-domain.com')) {
                    throw new Error('Only apps from trusted domains may use window context in this platform.');
                }
            }
            return super.getWindowContext(payload, callerIdentity);
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });
Copy

This API is called during the () call. Gets the current state of a particular window and its views and returns an object that can be added to the windows property. Override this function if you wish to mutate each window snapshot during the () call

Handles subsequent launch attempts of the current platform. Attempts to launch appManifestUrl passed as userAppConfigArgs. If no appManifestUrl is present will attempt to launch using the requesting manifest snapshot. If no appManifestUrl or snapshot is available nothing will be launched.

Handles the closing of a Window and/or its Views. Called in PlatformProvider.closeWindow. The return of PlatformProvider.getUserDecisionForBeforeUnload is passed into this method.

Called when a window's customContext is updated. Responsible for raising the host-context-updated event on that window's child views.

Called when a snapshot is being applied and some windows in that snapshot would be fully or partially off-screen. Returns an array of windows with modified positions, such that any off-screen windows are positioned in the top left corner of the main monitor.

Example

const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
        async positionOutOfBoundsWindows(
            snapshot, // The snapshot currently being applied
            outOfBoundsWindows // An array of options for all windows that would be fully or partially off-screen.
        ) {
            // By default, this function cascades out-of-bounds windows from the top left of the main monitor.
            // Perhaps we wish to instead position all such windows on the bottom right.

            // First, find the coordinates of the bottom right of the primary monitor
            const {
                primaryMonitor: {
                    availableRect: { right, bottom }
                }
            } = await fin.System.getMonitorInfo();

            // Update the coordinates of each out-of-bounds window to be bottom right
            const newWindows = snapshot.windows.map((windowOptions) => {
                if (outOfBoundsWindows.find(w => w.name === windowOptions.name)) {
                    // If the window is out of bounds, set a new initial top and left
                    const { defaultHeight, defaultWidth } = windowOptions;
                    return {
                        ...windowOptions,
                        defaultTop: bottom - defaultHeight,
                        defaultLeft: right - defaultWidth
                    }
                } else {
                    return windowOptions;
                }
            })

            // Return all windows with desired bounds
            return newWindows;
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });
Copy

Closes the current Platform and all child windows and views.

Remarks

Allows overriding a platform's default shutdown behavior. All calls to Platform.quit will pass through the override.

Example

const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
        async quit(payload, callerIdentity) {
            // Perhaps in our platform, we wish to take a snapshot and save it somewhere before shutting down
            const snapshot = await this.getSnapshot();
            await saveSnapshot(snapshot);
            return super.quit(payload, callerIdentity);
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });

async function saveSnapshot(snapshot) {
    // Save the snapshot in localstorage, send to a server, etc.
}
Copy

Replaces a Platform window's layout with a new layout. Any views that were in the old layout but not the new layout will be destroyed.

Remarks

Allows overriding a platform's default replaceLayout behavior. All calls to Platform#replaceLayout Platform.replaceLayout will pass through the override.

Example

const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
        async replaceLayout(payload, callerIdentity) {
            // Perhaps in our platform, we wish to save an updated snapshot each time a layout is replaced
            await super.replaceLayout(payload, callerIdentity);
            const updatedSnapshot = await fin.Platform.getCurrentSync().getSnapshot();
            await saveSnapshot(updatedSnapshot);
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });

async function saveSnapshot(snapshot) {
    // Save the snapshot in localstorage, send to a server, etc.
}
Copy

Handles requests to set a window's context. target may be a window or a view. If it is a window, that window's customContext will be updated. If it is a view, the customContext of that view's current host window will be updated.

Remarks

Allows overriding a platform's default setWindowContext behavior. All calls to Platform.setWindowContext will pass through the override.

Example

const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
        async setWindowContext(payload, callerIdentity) {
            // Perhaps in our platform, we wish to only take context updates from windows
            // and ignore updates sent from views.
            if (payload.entityType === 'view') {
                throw new Error('Updating window context from a view is not permitted in this platform.');
            }
            return super.setWindowContext(payload, callerIdentity);
        }
    }
    return new Override();
}

fin.Platform.init({ overrideCallback });
Copy