From bd923838c108c0ea693f3a158a5d1ca09cd317b3 Mon Sep 17 00:00:00 2001
From: Kilian Valkhof <kilian@kilianvalkhof.com>
Date: Thu, 9 Jan 2020 18:29:22 +0100
Subject: [PATCH] docs: initial document for comparing web embeds (#20478)

Co-authored-by: Felix Rieseberg <felix@felixrieseberg.com>
Co-authored-by: Mark Lee <malept@users.noreply.github.com>
---
 docs/README.md              |  1 +
 docs/tutorial/web-embeds.md | 22 ++++++++++++++++++++++
 2 files changed, 23 insertions(+)
 create mode 100644 docs/tutorial/web-embeds.md

diff --git a/docs/README.md b/docs/README.md
index e10b893ef166..2f0a2abc6d57 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -53,6 +53,7 @@ an issue:
   * [Native File Drag & Drop](tutorial/native-file-drag-drop.md)
   * [Offscreen Rendering](tutorial/offscreen-rendering.md)
   * [Supporting macOS Dark Mode](tutorial/mojave-dark-mode-guide.md)
+  * [Web embeds in Electron](tutorial/web-embeds.md)
 * [Accessibility](tutorial/accessibility.md)
   * [Spectron](tutorial/accessibility.md#spectron)
   * [Devtron](tutorial/accessibility.md#devtron)
diff --git a/docs/tutorial/web-embeds.md b/docs/tutorial/web-embeds.md
new file mode 100644
index 000000000000..1b260b775c2d
--- /dev/null
+++ b/docs/tutorial/web-embeds.md
@@ -0,0 +1,22 @@
+# Web embeds in Electron
+
+If you want to embed (third party) web content in an Electron `BrowserWindow`, there are three options available to you: `<iframe>` tags, `<webview>` tags, and `BrowserViews`. Each one offers slightly different functionality and is useful in different situations. To help you choose between these, this guide will explain the differences and capabilities of each.
+
+## Iframes
+
+Iframes in Electron behave like iframes in regular browsers. An `<iframe>` element in your page can show external web pages, provided that their [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) allows it. To limit the amount of capabilities a site in an `<iframe>` tag, it's recommended to use the [`sandbox` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-sandbox) and only allow the capabilities you want to support.
+
+## WebViews
+
+[WebViews](../api/webview-tag.md) are based on Chromium's WebViews and are not explicitly supported by Electron. We do not guarantee that the WebView API will remain available in future versions of Electron. This is why, if you want to use `<webview>` tags, you will need to set `webviewTag` to `true` in the `webPreferences` of your `BrowserWindow`.
+
+WebViews are a custom element (`<webview>`) that will only work inside Electron.
+They are implemented as an "out-of-process iframe". This means that all communication with the `<webview>` is done asynchronously using IPC. The `<webview>` element has many custom methods and events, similar to `webContents`, that allow you much greater control over the contents.
+
+Compared to an `<iframe>`, `<webview>` tends to be slightly slower but offers much greater control in loading and communicating with the third party content and handling various events.
+
+## BrowserViews
+
+[BrowserViews](../api/browser-view.md) are not part of the DOM - instead, they are created in and controlled by your main process. They are simply another layer of web content on top of your existing window. This means that they are completely separate from your own `BrowserWindow` content and that their position is not controlled by the DOM or CSS but by setting the bounds in the main process.
+
+BrowserViews offer the greatest control over their contents, since they implement the `webContents` similarly to how a `BrowserWindow` implements it. However, they are not part of your DOM but are overlaid on top of them, which means you will have to manage their position manually.