From 7a403fd723d135b27d2d5225db916d2502ffb3e8 Mon Sep 17 00:00:00 2001
From: Erik Lumme <erik@vaadin.com>
Date: Wed, 13 Sep 2017 14:14:16 +0300
Subject: [PATCH] Migrate OpeningAUIInAPopupWindow

---
 .../OpeningAUIInAPopupWindow.asciidoc         | 54 +++++++++++++++++++
 documentation/articles/contents.asciidoc      |  1 +
 2 files changed, 55 insertions(+)
 create mode 100644 documentation/articles/OpeningAUIInAPopupWindow.asciidoc

diff --git a/documentation/articles/OpeningAUIInAPopupWindow.asciidoc b/documentation/articles/OpeningAUIInAPopupWindow.asciidoc
new file mode 100644
index 0000000000..e9cfc5ccb9
--- /dev/null
+++ b/documentation/articles/OpeningAUIInAPopupWindow.asciidoc
@@ -0,0 +1,54 @@
+[[opening-a-ui-in-a-popup-window]]
+Opening a UI in a popup window
+------------------------------
+
+To open a new popup window in the browser showing another part of your
+application, you can use the new `BrowserWindowOpener` extension. Any
+component that you extend with `BrowserWindowOpener` will make clicking
+the component open a new browser window with some options for the
+content. Opening a popup this way helps you bypass most popup blockers.
+
+One of the things that `BrowserWindowOpener` can be configured to open
+in the new window is a new instance of a Vaadin UI class.
+
+[source,java]
+....
+public class OpeningUIInPopup extends UI {
+  @Override
+  protected void init(VaadinRequest request) {
+    Button popupButton = new Button("Open popup with MyPopupUI");
+
+    BrowserWindowOpener popupOpener = new BrowserWindowOpener(MyPopupUI.class);
+    popupOpener.setFeatures("height=300,width=300");
+    popupOpener.extend(popupButton);
+
+    // Add a parameter
+    popupOpener.setParameter("foo", "bar");
+
+    // Set a fragment
+    popupOpener.setUriFragment("myfragment");
+
+    setContent(popupButton);
+  }
+}
+
+public class MyPopupUI extends UI {
+  @Override
+  protected void init(VaadinRequest request) {
+    setContent(new Label("This is MyPopupUI where parameter foo="
+        + request.getParameter("foo") + " and fragment is set to "
+        + getPage().getUriFragment()));
+  }
+}
+....
+
+In this example, a `Button` is created and extended with a
+`BrowserWindowOpener`. Furthermore, the size of the popup window is
+defined. See
+https://developer.mozilla.org/en-US/docs/DOM/window.open#Position_and_size_features
+for a description of the commonly supported features. If you don't
+define any features, the browser will use its default setting which
+usually makes it open a new tab instead of opening a popup window.
+
+The `BrowserWindowOpener` can also be used to open a `Resource` or any
+URL that you define using different constructors.
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index 3ff511eb00..cd8bc34207 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -85,3 +85,4 @@ are great, too.
 - link:GettingStartedOnNetBeans.asciidoc[Getting started on NetBeans]
 - link:ComponentAddonProjectSetupHOWTO.asciidoc[Component add-on project setup how-to]
 - link:CreatingAThemeUsingSass.asciidoc[Creating a theme using Sass]
+- link:OpeningAUIInAPopupWindow.asciidoc[Opening a UI in a popup window]
-- 
2.39.5