feat: Allow creation of new window to be customizable.

[khalwa]

Description of Change

This PR adds a way to manually control the creation of a guest window in webContents.setWindowOpenHandler. My main motivation for this change is to have the possibility to properly handle new windows in form of BrowserView (in order to support window.opener I need to pass appropriate WebContents when creating an instance of it).

I am not an expert so I don't know what important things I could've missed introducing this change but I am hoping that with your guidance we'll be able to work on this PR and make such functionality possible in Electron.

This is a copy of #33134 but this time set up from my private fork.

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation, tutorials, templates and examples are changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Extended webContents.setWindowOpenHandler to support manual creation of BrowserWindow.

[samuelmaddock]

API LGTM

[nornagon]

API LGTM

[samuelmaddock]

Linux build failure is a known flaky test

[welcome]

Congrats on merging your first pull request! 🎉🎉🎉

[release-clerk]

Release Notes Persisted

Extended webContents.setWindowOpenHandler to support manual creation of BrowserWindow.

[PalmerAL]

@khalwa Sorry if I'm not understanding something, but how is this API supposed to work with WebContentsView (which is replacing BrowserView)?

With a BrowserView, the options.webContents can be passed in, but WebContentsView doesn't have an equivalent option. If I do this:

return {
        action: 'allow',
        createWindow: function (options) {
          const view = new WebContentsView(options)
          return view.webContents
        }
      }

I get:

Error: Invalid webContents. Created window should be connected to webContents passed with options object.

[khalwa]

@PalmerAL Hi! This PR was started two years ago (see reference in description) when WebContentsView was not introduced yet so I was creating it with mainly BrowserView in mind. I was checking what you have said and I was not able to make this work with WebContentsView either. I am not sure if it allows setting webContents by the constructor. If we take a look at the implementation of BrowserView it is now using internally WebContentsView and in the constructor we see that it actually sets the webContents as a "hidden field" of webPreferences object: https://github.com/electron/electron/blob/main/lib/browser/api/browser-view.ts#L15-L17. So in order for it to work with WebContentsView I think there needs to be a way to pass webContents to it programatically, but its not documented anywhere and I do not know how/if it is possible in the current implementation to do it.

Edit:
Here is a code that I tried out in Electron Fiddle and it made this work with WebContentsView. It uses Electron internals and should not be used but kind of proves that there is a problem with setting webContents for that type.

mainWindow.webContents.setWindowOpenHandler((details) => {
    return {
      action: 'allow',
      createWindow: (options) => {
        const webPreferences = {
          ...options.webPreferences,
        }
        webPreferences.type = "browserView";
        
        const v8Util = process._linkedBinding('electron_common_v8_util');
        v8Util.setHiddenValue(webPreferences, "webContents", options.webContents);

        const webContentsView = new WebContentsView({
          webPreferences
        })
        webContentsView.setBounds({x: 0, y: 0, width: 300, height: 300})
        mainWindow.contentView.addChildView(webContentsView)
        return webContentsView.webContents
      }
    }
  })

[PalmerAL]

@khalwa Thanks! That matches my investigation too.

@nornagon Since it looks like you wrote the WebContentsView implementation and also reviewed this previously:

1. Is there a reason that WebContentsView doesn't expose a public option to create a view with a pre-existing contents like BrowserView did?
2. What would be the process for proposing an API change to make these two things work together?

[PalmerAL]

#42054