API changes:

• Deprecate webContents new-window event in favor of webContents.setWindowOpenHandler(handler) and did-create-window

  new-window is fired after the contents is already created by Chrome. This is a problem when the application wants to prevent that window from being opened, as killing the window during initialization causes many problems and leads to the inevitable crash. Instead, we'll allow cancellation/customization of the new window before it's created. In congress with a change to set WebPreferences via IPC instead of the command line, this allows us to completely* change the child window's BrowserWindowConstructorOptions, even for in-process windows.

  *With the exception of a few outstanding preferences that we need early in initialization, like offscreen and nodeIntegrationInWorker. These could be fixed with some effort.

  Old way:

  mainWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures) => {
      Object.assign(options, {
        modal: true,
      });
      childWindow = new BrowserWindow(options);
      event.newGuest = childWindow;
  });
  
  // or
  
  mainWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures) => {
      event.preventDefault();
  });

  New way:

  mainWindow.webContents.setWindowOpenHandler(({ url, frameName }) => {
    return {
      action: 'allow',
      overrideBrowserWindowOptions: {
        modal: true,  
      }
    }
  });
  mainWindow.webContents.on('did-create-window', (win, { url, frameName, options, disposition, additionalFeatures, referrer, postData }) => {
    childWindow = win;
  });
  
  // or
  
  mainWindow.webContents.setWindowOpenHandler(({ url, frameName }) => {
    return { action: 'deny' };
  });

• (internal API) webFrame.getWebPreference(prefName)

  Previously, preferences were stuffed into command line switches so that the renderer could look and see what settings it was supposed to be using. However, this wouldn't work for in-process child windows. Instead, we'll stuff Electron preferences into the struct that Chrome already uses for this sort of thing and add an API for the renderer to retreive those preferences. At the moment, only Electron-specific WebPreferences are available for lookup, but it would be easy to add Chromium-defined prefs like defaultFontSize, for example.

  const { webFrame } = require('electron');
  const isContextIsolationEnabled = webFrame.getWebPreference('contextIsolation');

Implementation details:

• Allowing for in-process WebPreference changes

  Prior to this change, WebPreferences were set via the command line, which meant that in-process child windows were forced to inherit WebPreferences from their parent. Now, we overload the Chrome WebPreference struct with our own properties so they are accessible in the renderer (via a new webFrame.getWebPreference).

  

• Some behavior changes that make window opening less, um, surprising.

  • Non-security related BrowserWindowConstructorOptions are no longer inherited from the parent. This was confusing when you had to "undo" preferences that may have been set in a different part of your app.
  • window.open features keys without values are now interpreted as true, to w3c spec.
  • We no longer check for cycles in BrowserWindowOptions. (#8340)

Checklist

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

Release Notes

Notes: Add setWindowOpenHandler API for renderer-created child windows, and deprecate new-window event.