Popups

We've already discussed that all UI is still owned by the app and all a plugin does is instruct the app to add this UI. Because of this, popups become a bit more complicated. The main problem is that the context of a direct user interaction is broken as the UI element that was interacted with does not belong to the plugin (i-frame). When a popup tries to be open outside of a direct user interaction, it is blocked until the user allows this via a prompt the browser shows. Asking the end-user to allow popups is admittedly not the greatest user experience.

This is one of the drawbacks of the API, but albeit not ideal, we are still providing a way to open popups without breaking user interaction context.

The following UI elements can open a popup: ToolbarButton, ParticipantActionsButton, Form(on submit), Prompt(on submit)

Intent to open a popup is indicated by the opensPopup property as part of the element creation phase (addButton, showForm, showPrompt).

    opensPopup: {
        id: 'form-docs',
        openParams: [
            'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form',
            '',
            'width=800,height=600',
        ],
    },

The plugin does not need to specify anything else if the popup is opened regardless of the user input.
If opening the popup depends on what the user input is, a guard function can be added like so:

window.plugin.popupManager.add('form-docs', input => {
  if (input.action === FormPrompt.prompt.primaryAction) {
    return true;
  }
  return false;
});

Note: The first argument of the function needs to match the `id` that was specified in the `opensPopup` property.

The following map shows the relationship between the specific UI elements and their guard function input. Note: The function always needs to return a boolean to indicate whether or not to open the popup.

ToolbarButton: no guard function
ParticipantActionsButton: ({participantUuid:string}) => boolean
Prompt: ({action: string}) => boolean // action is Primary or Secondary action
Form: (inputObject) => boolean // inputObject is dynamically generated based on form entries