Shows a popup window. Including a name in options will attempt to show an existing window as a popup, if that window doesn't exist or no name is included a window will be created. If the caller view or the caller view's parent window currently has a popup window open, calling showPopupWindow again will dismiss the currently open popup window before showing the new popup window. Also, if the caller view is destroyed or detached, the popup will be dismissed.

NOTE: in the case where the window being shown as a popup needs to be created, it is a child of the caller view's parent window.

Default options

initialOptions:

 alwaysOnTop: true

 autoShow: true

 frame: false

 includeInSnapshots: false

 resizable: false

 saveWindowState: false

blurBehavior: 'close'

hideOnClose: false

focus: true

resultDispatchBehavior: 'close'

x: 0

y: 0

height: 300

width: 300

Examples

Create and show a single-use popup window that returns a single result to the caller. initialOptions allows us to pass window options to the popup window that will be created. resultDispatchBehavior: 'close' ensures that once the popup window calls dispatchPopupResult it is closed. blurBehavior: 'close' will yield a dismissed result should the popup window lose focus.

const result = await fin.me.showPopupWindow({
    initialOptions: {
        frame: false
    },
    url: '<my_popup_url>',
    resultDispatchBehavior: 'close',
    blurBehavior: 'close',
    focus: true,
    height: 300,
    width: 300,
    x: 0,
    y: 0
});

Same as above but using an existing window as a popup by referencing its name. NOTE: if a window with the name provided doesn't exist, it will be created.

const result = await fin.me.showPopupWindow({
    initialOptions: {
        frame: true
    },
    name: 'my-popup', // shows the 'my-popup' window if it exists, otherwise creates it
    url: '<my_popup_url>', // navigates to this url if it doesn't match the location.href of the 'my-popup' window
    resultDispatchBehavior: 'close',
    blurBehavior: 'close',
    focus: true,
    hideOnClose: true, // persist window on 'dismissed' result, alternatively change onResultDispatch and blurBehavior to 'hide'
    height: 300,
    width: 300,
    x: 0,
    y: 0
});

Create and show a popup window that is able to return multiple results to the caller via an onPopupResult callback. Each time the popup window calls dispatchPopupResult, the callback will be executed on the result. Once the popup window is closed or hidden, the showPopupWindow promise will resolve with a dismissed result that will include the most recently dispatched result as lastDispatchResult.

const popupResultCallback = (payload) => {
       if (payload.result === 'clicked') {
           if (payload.data.topic === 'color-changed') {
               // do something like
               // setColor(payload.data.value);
           }
       } 
};

await fin.me.showPopupWindow({
    initialOptions: {
        frame: false
    },
    url: '<my_popup_url>',
    resultDispatchBehavior: 'none',
    blurBehavior: 'close',
    focus: true,
    height: 300,
    width: 300,
    x: 0,
    y: 0,
    onPopupResult: popupResultCallback
});

Same as above but using an existing window as a popup.

const popupResultCallback = (payload) => {
       if (payload.result === 'clicked') {
           if (payload.data.topic === 'color-changed') {
               // do something like
               // setColor(payload.data.value);
           }
       } 
};

await fin.me.showPopupWindow({
    initialOptions: {
        frame: false
    },
    name: 'my-popup', // shows the 'my-popup' window if it exists, otherwise creates it
    url: '<my_popup_url>', // navigates to this url if it doesn't match the location.href of the 'my-popup' window
    resultDispatchBehavior: 'none',
    blurBehavior: 'hide',
    focus: true,
    hideOnClose: true, // we can just use this or we can change blurBehavior to 'hide'
    height: 300,
    width: 300,
    x: 0,
    y: 0,
    onPopupResult: popupResultCallback
});

Create or show a popup window that disables user movement (positioning and resizing) in the caller view's parent window by using blurBehavior: 'modal'.

const result = await fin.me.showPopupWindow({
    initialOptions: {
        frame: false
    },
    url: '<my_popup_url>',
    resultDispatchBehavior: 'close',
    blurBehavior: 'modal',
    focus: true,
    height: 300,
    width: 300,
    x: 0,
    y: 0
});

Create a popup window as a modal. NOTE: The only way to ensure true modal behavior is to create the window being shown as a popup with a modalParentIdentity that uses the caller view's parent window identity.

const result = await fin.me.showPopupWindow({
    initialOptions: {
        frame: false,
        modalParentIdentity: fin.me.identity
    },
    url: '<my_popup_url>',
    resultDispatchBehavior: 'close',
    blurBehavior: 'modal',
    focus: true,
    height: 300,
    width: 300,
    x: 0,
    y: 0
});

Pass data to a popup window that is available when the popup is shown. NOTE: this is just one example for a use of additionalOptions, it can be used to update any updatable window options when creating or showing an existing window as a popup.

const result = await fin.me.showPopupWindow({
    additionalOptions: {
        customData: {
            foo: 'bar'
        }
    },
    url: '<my_popup_url>',
    resultDispatchBehavior: 'close',
    blurBehavior: 'close',
    focus: true,
    height: 300,
    width: 300,
    x: 0,
    y: 0
});

// Access from the popup window context like so:
const { customData } = await fin.me.getOptions();
const { foo } = customData;

Execute a callback on the popup's OpenFin window when the popup is shown.

const popupWindowCallback = async (win) => {
    await win.flash();
};

const result = await fin.me.showPopupWindow({
    url: '<my_popup_url>',
    resultDispatchBehavior: 'close',
    blurBehavior: 'close',
    focus: true,
    height: 300,
    width: 300,
    x: 0,
    y: 0,
    onPopupReady: popupWindowCallback;
});