docs: add <webview> new-window event removal to breaking-changes.md

[miniak]

Description of Change

Fix #34678. Follow-up to #34526

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• relevant documentation, tutorials, templates and examples are changed or added

Release Notes

Notes: none

[miniak]

@nornagon I am wondering whether we should re-implement the new-window event on <webview> using the new API somehow as it's kind of complicated to handle this compared to quite straightforward replacing of the webContents new-window event with setWindowOpenHandler(). On the other handle the renderer cannot do event.preventDefault() anyway, so it's not that useful. What do you think?

[nornagon]

We should probably give some guidance for how to move forward for apps that depend on this. Mention setWindowOpenHandler and link to docs, but note that there is no automatic forwarding to the embedder?

[miniak]

the problem here is that the forwarding is kind of complicated to do on app-level, so mentioning setWindowOpenHandler without showing how to do it is not that useful

[nornagon]

it ought to be possible to figure out which webview an open handler comes from, right...?

[miniak]

you need to get the webContents of the <webview> first, set setWindowOpenHandler there and then you would need to send an IPC to a preload script in the <webview>, which would then call ipcRenderer.sendToHost() to get it as ipc-message event on the <webview> element, which is routed via the main process again

[miniak]

something like this
main.js

mainWindow.webContents.on('will-attach-webview', (event, webPreferences) => {
  webPreferences.preload = path.join(__dirname, 'preload.js');
});

mainWindow.webContents.on('did-attach-webview', (event, wc) => {
  wc.setWindowOpenHandler(details => {
    wc.send('new-window', details);
    return { action: 'allow' };
  });
});

preload.js

const { ipcRenderer } = require('electron');

ipcRenderer.on('new-window', (event, data) => {
  ipcRenderer.sendToHost('new-window', data);
});

index.js

const webview = document.querySelector('webview')
webview.addEventListener('ipc-message', (event) => {
  if (event.channel === 'new-window') {
    const [details] = event.args;
    console.log(details);
  }
});

[miniak]

But then you would send the IPC normally instead of getting it via the webview element and it will have to be passed through the contextBridge

[nornagon]

you can definitely emit an event on a webview from the preload without a sendToHost IPC! it's just an EventTarget, you can make up an event and fire it however you like.

here's an example: https://gist.github.com/408586025cefd8a0396869e3aa5a1fa4

one snag i ran into is that it's not possible to call webview methods from the preload, in particular wv.getWebContentsId() would have been useful to make an example that would match the event to the right webview by querySelectorAll('webview').forEach(wv => wv.getWebContentsId() === wcId && wv.dispatchEvent(new Event('new-window'))) or so. this seems kind of like an oversight, but doesn't fundamentally prevent the technique from working.

[miniak]

@nornagon can we merge this for now and address a better code sample in a follow-up?

[nornagon]

@miniak no. I'm specifically commenting on the content of this documentation change with a request to improve the documentation. I've given a specific example of code which I think is better.

[miniak]

added your example as fiddle

[codebytere]

@nornagon is this still blocked re #36985 (comment)?

[nornagon]

@codebytere I believe the PR hasn't changed since that comment, so yes.

[miniak]

@nornagon could you please help with the docs? I got quite busy with some Teams internal stuff and didn’t have time for this PR :(

[jkleinsc]

Blocking this until #36985 (comment) is resolved.

[release-clerk]

No Release Notes

[trop]

I have automatically backported this PR to "25-x-y", please check out #38523

[trop]

I have automatically backported this PR to "22-x-y", please check out #38524

[trop]

I have automatically backported this PR to "24-x-y", please check out #38525

[trop]

I have automatically backported this PR to "23-x-y", please check out #38526