From afdf52b05369aafdf2132f72639de065da5e6884 Mon Sep 17 00:00:00 2001
From: Ryohei Ikegami <iofg2100@gmail.com>
Date: Sun, 19 Mar 2017 18:35:12 +0900
Subject: [PATCH] Add docs for useNativeWindowOpen

---
 docs/api/browser-window.md |  1 +
 docs/api/window-open.md    | 24 ++++++++++++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index 3bdc4deddaa..75135d55e94 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -295,6 +295,7 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       'Electron Isolated Context' entry in the combo box at the top of the
       Console tab. **Note:** This option is currently experimental and may
       change or be removed in future Electron releases.
+    * `useNativeWindowOpen` Boolean (optional) - Whether to use native `window.open()`.
 
 When setting minimum or maximum window size with `minWidth`/`maxWidth`/
 `minHeight`/`maxHeight`, it only constrains the users. It won't prevent you from
diff --git a/docs/api/window-open.md b/docs/api/window-open.md
index 56216f551a0..7bc6b3ef2a7 100644
--- a/docs/api/window-open.md
+++ b/docs/api/window-open.md
@@ -41,3 +41,27 @@ has to be a field of `BrowserWindow`'s options.
 
 Sends a message to the parent window with the specified origin or `*` for no
 origin preference.
+
+### Use Native `window.open()`
+
+If you want to use native `window.open()` implementation, pass `useNativeWindowOpen: true` in `webPreferences` option.
+Native `window.open()` allows synchronous access to opened windows so it is convenient choise if you need to open a dialog or a preferences window.
+
+The creation of the `BrowserWindow` is customizable in `WebContents`'s `new-window` event.
+
+```javascript
+mainWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures) => {
+  if (url.endsWith("modal.html")) {
+    // open window as modal
+    event.preventDefault()
+    Object.assign(options, {
+      modal: true,
+      parent: mainWindow,
+      width: 100,
+      height: 100
+    })
+    modal = new BrowserWindow(options)
+    modal.loadURL(url)
+    event.newGuest = modal
+  }
+```