AboutSupportDeveloper GuideVersion 19.1.22

Interface WorkspacePlatformProvider

Hierarchy

  • PlatformProvider
    • WorkspacePlatformProvider

Methods

  • Implementation for adding custom default page

    Parameters

    • payload: AddDefaultPagePayload

      AddDefaultPagePayload

    Returns Promise<void>

  • Handles requests to apply a snapshot to the current Platform.

    Parameters

    • payload: ApplySnapshotPayload

      Payload containing the snapshot to be applied, as well as any options.

    • Optional identity: Identity_4

      Identity of the entity that called Platform.Platform#applySnapshot Platform.applySnapshot. Undefined if called internally (e.g. when opening the initial snapshot).

    Returns Promise<void>

    Remarks

    Allows overriding a platform's default snapshot behavior. All calls to Platform#applySnapshot 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 });
  • Applies a workspace to the user's desktop. Makes that workspace the active workspace.

    Returns Promise<boolean>

    true if the workspace was applied, false if the workspace was not applied.

  • 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.

    Parameters

    • views: View_2[]

      Array of Views

    Returns Promise<ViewStatuses>

  • Closes a view

    Parameters

    • payload: CloseViewPayload

      Specifies the target view to be closed.

    • Optional identity: Identity_4

      Identity of the entity that called Platform.Platform#closeView Platform.closeView.

    Returns Promise<any>

    Remarks

    Allows overriding a platform's default view closing behavior. All calls to Platform#closeView 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.
    }
  • 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.Platform#closeWindow Platform.closeWindow.

    Parameters

    • payload: CloseWindowPayload

      Object that contains the Window Identity and related options.

    • callerIdentity: Identity_4

    Returns Promise<void>

    Remarks

    This method calls a number of Platform Provider methods:

    • PlatformProvider#getViewsForWindowClose
    • PlatformProvider#checkViewsForPreventUnload
    • PlatformProvider#getUserDecisionForBeforeUnload
    • PlatformProvider#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 });
  • Implementation for creating a copy of a page. Called when a page is Saved-As or Duplicated.

    Note: The page.layout and page.panels property cannot be overridden for 'Save As' operations, the page.layout and page.panels property provided in the return value will be ignored, and the layout and panels of the original page will remain after 'Save As' is performed.

    Parameters

    Returns Promise<Page>

  • Implementation for creating a saved page in persistent storage.

    Parameters

    Returns Promise<void>

  • Implementation for creating a saved workspace in persistent storage.

    Parameters

    Returns Promise<void>

  • Override when you need to add custom functionality when creating a view.

    Parameters

    Returns Promise<View_2>

  • Handles requests to create a window in the current platform.

    Parameters

    • options: PlatformWindowCreationOptions
    • Optional identity: Identity_4

      If Platform.Platform#createWindow Platform.createWindow was called, the identity of the caller will be here.

    Returns Promise<_Window>

    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 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 });
  • Implementation for deleting a saved page in persistent storage.

    Parameters

    • id: string

      of the id of the page to delete.

    Returns Promise<void>

  • Implementation for deleting a saved workspace in persistent storage.

    Parameters

    • id: string

      of the id of the workspace to delete.

    Returns Promise<void>

  • Handles requests to fetch manifests in the current platform.

    Parameters

    • payload: FetchManifestPayload

      Payload containing the manifestUrl to be fetched.

    • callerIdentity: Identity_4

      If Platform.Platform#fetchManifest Platform.fetchManifest was called, the identity of the caller will be here.

    Returns Promise<any>

    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 Platform.launchContentManifest and fins links fetch manifests. All calls to Platform#fetchManifest 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 });
  • Implementation for getting the dock provider from persistent storage.

    Parameters

    • id: string

      The id of the dock provider to get.

    Returns Promise<DockProviderConfigWithIdentity>

  • Implementation for getting current selected language

    Returns Promise<"en-US" | "ja-JP" | "zh-CN" | "ko-KR" | "ru-RU" | "de-DE" | "zh-Hant">

    language in ISO language code

  • Implementation for getting a single page in persistent storage.

    Parameters

    • id: string

    Returns Promise<Page>

    a page object or undefined if page doesn't exist.

  • Implementation for getting a list of saved pages from persistent storage.

    Parameters

    • Optional query: string

      an optional query.

    Returns Promise<Page[]>

  • Implementation for getting a single workspace in persistent storage.

    Parameters

    • id: string

    Returns Promise<Workspace>

    a workspace object or undefined if workspace doesn't exist.

  • Implementation for getting a list of saved workspaces from persistent storage.

    Parameters

    • Optional query: string

      an optional query.

    Returns Promise<Workspace[]>

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

    Parameters

    • payload: undefined

      Undefined unless you've defined a custom getSnapshot protocol.

    • identity: Identity_4

      Identity of the entity that called Platform.Platform#getSnapshot Platform.getSnapshot.

    Returns Promise<Snapshot>

    Snapshot of current platform state.

    Remarks

    Allows overriding a platform's default snapshot behavior. All calls to Platform#getSnapshot 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.
    }
  • Handle the decision of whether a Window, Page or specific View should close when trying to prevent an unload. This is meant to be overridden. Called in closeWindow and closeView.

    When closing a Page, this override is called by shouldPageClose and page proceeds to close if all views passed in are determined to close. In this case, the closeType property will have 'page' value.

    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.

    Parameters

    Returns Promise<BeforeUnloadUserDecision>

    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
    }
  • 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.

    Parameters

    • windowId: Identity_4

    Returns Promise<View_2[]>

  • 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.

    Parameters

    • payload: GetWindowContextPayload

      Object containing the requested context update, the target's identity, and the target's entityType.

    • Optional identity: Identity_4

      Identity of the entity that called Platform.Platform#getWindowContext Platform.getWindowContext. Undefined when getWindowContext is called internally (e.g. when getting a window's context for the purpose of raising a "host-context-changed" event on a reparented view).

    Returns Promise<any>

    The new context.

    Remarks

    Allows overriding a platform's default getWindowContext behavior. All calls to Platform#getWindowContext 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 });
  • Experimental

    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 OpenFin.Snapshot.windows property. Override this function if you wish to mutate each window snapshot during the () call

    Parameters

    • identity: Identity_4
    • callerIdentity: Identity_4

    Returns Promise<WindowCreationOptions>

  • Implementation for handling Workspace analytics events

    Parameters

    Returns Promise<void>

  • Experimental

    This method is called to handle errors with view creation and initial navigation during layout creation. Overriding this method enables catching the error and correcting behavior (ie navigating to an error page).

    • To indicate that the error has been handled, view creation should be treated as successful return {identity: viewIdentity, success: true}.
    • Not returning anything will cause the layout-initialized event to include the view as failed with the original error.
    • Throwing an error will update the error on the event payload of layout-initialized to the thrown error.

    Parameters

    • viewIdentity: Identity_4

      Identity of the view

    • error: Error

      error thrown during a view creation

    Returns Promise<void | ViewCreationSuccess>

    Example

    const overrideCallback = (PlatformProvider) => {
    class Override extends PlatformProvider {
    async handleFailedViewCreation(viewIdentity, error) {
    const view = fin.View.wrapSync(viewId);
    try {
    // navigate to an error page
    await view.navigate('http://localhost:3000/errorPage.html');
    // resolve a success result after redirecting to a error page
    return {identity: viewIdentity, success: true};
    } catch(e) {
    // layout-initialized event will include this view with the error
    throw error;
    }
    }
    }
    return new Override();
    }

    fin.Platform.init({ overrideCallback });
  • Implementation for detecting if a page change qualifies as putting the page in an unsaved state.

    Parameters

    • payload: HandlePageChangesPayload

      the page with new changes and the identity of the OF window where the page change occured.

    Returns Promise<ModifiedPageState>

  • This override is called upon closing of a window by user and its return value determines whether the window should proceed closing. pagesPreventingClose and pagesNotPreventingClose represent pages in the window, grouped based on the value returned by shouldPageClose override for each page. Default implementation will abort closing of the window if any of the pages within it are prevented from closing.

    Parameters

    • payload: HandlePagesAndWindowClosePayload

      Contains pages that were prevented from closing, pages that weren't, and identity of the window

    Returns Promise<HandlePagesAndWindowCloseResult>

    Promise<{shouldWindowClose: boolean}> which determines whether closing of the window will proceed

  • 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.

    Parameters

    • payload: RunRequestedEvent_2

    Returns Promise<void>

  • Implementation for deciding whether a modal informing about loss of unsaved changes will be displayed when closing a page. The default implementation returns { shouldShowModal: true } if the page has unsaved changes (hasUnsavedChanges page property) and false otherwise.

    Returns Promise<SaveModalOnPageCloseResult>

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

    Parameters

    • windowId: Identity_4
    • userDecision: BeforeUnloadUserDecision

      Decision object

    Returns Promise<void>

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

    Parameters

    • payload: OptionsChangedEvent

      The event payload for the window whose context has changed. The new context will be contained as payload.diff.customContext.newVal.

    Returns Promise<HostContextChangedPayload>

    The event that it raised.

  • Implementation for showing a global context menu given a menu template, handler callback, and screen coordinates. For an example of overriding, see WorkspacePlatformOverrideCallback.

    Parameters

    • req: OpenGlobalContextMenuPayload

      the payload received by the provider call

    • callerIdentity: Identity_4

      OF identity of the entity from which the request originated

    Returns Promise<void>

  • Implementation for showing a page tab context menu given a menu template, handler callback, and screen coordinates. For an example of overriding, see WorkspacePlatformOverrideCallback.

    Parameters

    • req: OpenPageTabContextMenuPayload

      the payload received by the provider call

    • callerIdentity: Identity_4

      OF identity of the entity from which the request originated

    Returns Promise<void>

  • Implementation for showing a context menu for save button given a menu template, handler callback, and screen coordinates. For an example of overriding, see WorkspacePlatformOverrideCallback.

    Parameters

    • req: OpenSaveButtonContextMenuPayload

      the payload received by the provider call

    • callerIdentity: Identity_4

      OF identity of the entity from which the request originated

    Returns Promise<void>

  • Implementation for showing a view tab context menu given a menu template, handler callback, and screen coordinates. For an example of overriding, see WorkspacePlatformOverrideCallback.

    Parameters

    • req: OpenViewTabContextMenuPayload

      the payload received by the provider call

    • callerIdentity: Identity_4

      OF identity of the entity from which the request originated

    Returns Promise<void>

  • 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.

    Parameters

    • snapshot: Snapshot

      The snapshot to be applied.

    • outOfBoundsWindows: WindowCreationOptions[]

      An array of WindowOptions for any windows that would be off-screen.

    Returns Promise<WindowCreationOptions[]>

    An array of WindowOptions with their position modified to fit on screen.

    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 });
  • Closes the current Platform and all child windows and views.

    Parameters

    • payload: undefined

      Undefined unless you have implemented a custom quite protocol.

    • identity: Identity_4

      Identity of the entity that called Platform.Platform#quit Platform.quit.

    Returns Promise<void>

    Remarks

    Allows overriding a platform's default shutdown behavior. All calls to Platform#quit 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.
    }
  • 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.

    Parameters

    • payload: ReplaceLayoutPayload

      Contains the target window and an opts object with a layout property to apply.

    • Optional identity: Identity_4

      Identity of the entity that called PlatformProvider#replaceLayout Platform.replaceLayout. Undefined if replaceLayout is called internally (e.g. while applying a snapshot).

    Returns Promise<void>

    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.
    }
  • Parameters

    • payload: ReplaceViewPayload
    • Optional identity: Identity_4

    Returns Promise<void>

  • Implementation for saving a dock provider config to persistent storage.

    Parameters

    • config: DockProviderConfigWithIdentity

      The new dock config to save to persistent storage.

    Returns Promise<void>

  • Implementation for setting the active page in a browser window. Called when the active page is changed and on browser window creation.

    Parameters

    Returns Promise<void>

  • Implementation for setting a language

    Parameters

    • locale: "en-US" | "ja-JP" | "zh-CN" | "ko-KR" | "ru-RU" | "de-DE" | "zh-Hant"

      in ISO language code format

    Returns Promise<void>

  • Implementation for setting selected theme scheme.

    Parameters

    Returns Promise<void>

  • 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.

    Parameters

    • payload: SetWindowContextPayload

      Object containing the requested context update, the target's identity, and the target's entityType.

    • Optional identity: Identity_4

      Identity of the entity that called Platform.Platform#setWindowContext Platform.setWindowContext. Undefined if setWindowContext is called internally (e.g. while applying a snapshot).

    Returns Promise<any>

    The new context.

    Remarks

    Allows overriding a platform's default setWindowContext behavior. All calls to Platform#setWindowContext 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 });
  • This override is called upon closing of the page by user or for each page in a window that is being closed by user.

    In case of closing a page individually, the close operation will be aborted if a False value is returned.

    In case of closing a window, the return value will be used to form payload of handlePagesAndWindowClose override, which determines whether the window should proceed with closing.

    Default behavior: if beforeunload is disabled for the platform, True is always returned. If enableBeforeUnload is set to true and getUserDecisionForBeforeUnload override is configured to respect beforeunload decisions of views, then True is only returned if no views are preventing unload.

    Parameters

    Returns Promise<ShouldPageCloseResult>

  • Implementation for updating a saved page in persistent storage.

    Parameters

    Returns Promise<void>

  • Implementation for updating a saved workspace in persistent storage.

    Parameters

    Returns Promise<void>