--- title: Handling Browser Windows order: 1 layout: page --- [[advanced.windows]] = Handling Browser Windows The UI of a Vaadin application runs in a web page displayed in a browser window or tab. An application can be used from multiple UIs in different windows or tabs, either opened by the user using an URL or by the Vaadin application. In addition to native browser windows, Vaadin has a [classname]#Window# component, which is a floating panel or __sub-window__ inside a page, as described in <>. * __Native popup windows__. An application can open popup windows for sub-tasks. * __Page-based browsing__. The application can allow the user to open certain content to different windows. For example, in a messaging application, it can be useful to open different messages to different windows so that the user can browse through them while writing a new message. * __Bookmarking__. Bookmarks in the web browser can provide an entry-point to some content provided by an application. * __Embedding UIs__. UIs can be embedded in web pages, thus making it possible to provide different views to an application from different pages or even from the same page, while keeping the same session. See <>. Use of multiple windows in an application may require defining and providing different UIs for the different windows. The UIs of an application share the same user session, that is, the [classname]#VaadinSession# object, as described in <>. Each UI is identified by a URL that is used to access it, which makes it possible to bookmark application UIs. UI instances can even be created dynamically based on the URLs or other request parameters, such as browser information, as described in <>. Because of the special nature of AJAX applications, use of multiple windows uses require some caveats. //// TODO Re-enable We will go through them later in <xref linkend="advanced.windows.caveats"/>. //// [[advanced.windows.popup]] == Opening Pop-up Windows ((("popup windows"))) ((("windows", "popup"))) Pop-up windows are native browser windows or tabs opened by user interaction with an existing window. Due to browser security reasons, it is made inconvenient for a web page to open popup windows using JavaScript commands. At the least, the browser will ask for a permission to open the popup, if it is possible at all. This limitation can be circumvented by letting the browser open the new window or tab directly by its URL when the user clicks some target. This is realized in Vaadin with the [classname]#BrowserWindowOpener# component extension, which causes the browser to open a window or tab when the component is clicked. [[advanced.windows.popup.ui]] === The Pop-up Window UI A popup Window displays an [classname]#UI#. The UI of a popup window is defined just like a main UI in a Vaadin application, and it can have a theme, title, and so forth. For example: [source, java] ---- @Theme("book-examples") public static class MyPopupUI extends UI { @Override protected void init(VaadinRequest request) { getPage().setTitle("Popup Window"); // Have some content for it VerticalLayout content = new VerticalLayout(); Label label = new Label("I just popped up to say hi!"); label.setSizeUndefined(); content.addComponent(label); content.setComponentAlignment(label, Alignment.MIDDLE_CENTER); content.setSizeFull(); setContent(content); } } ---- [[advanced.windows.popup.popping]] === Popping It Up A popup window is opened using the [classname]#BrowserWindowOpener# extension, which you can attach to any component. The constructor of the extension takes the class object of the UI class to be opened as a parameter. You can configure the features of the popup window with [methodname]#setFeatures()#. It takes as its parameter a comma-separated list of window features, as defined in the HTML specification. status=[parameter]#0|1#:: Whether the status bar at the bottom of the window should be enabled. [parameter]##:: scrollbars:: Enables scrollbars in the window if the document area is bigger than the view area of the window. resizable:: Allows the user to resize the browser window (no effect for tabs). menubar:: Enables the browser menu bar. location:: Enables the location bar. toolbar:: Enables the browser toolbar. height=[parameter]#value#:: Specifies the height of the window in pixels. width=[parameter]#value#:: Specifies the width of the window in pixels. For example: [source, java] ---- // Create an opener extension BrowserWindowOpener opener = new BrowserWindowOpener(MyPopupUI.class); opener.setFeatures("height=200,width=300,resizable"); // Attach it to a button Button button = new Button("Pop It Up"); opener.extend(button); ---- The resulting popup window, which appears when the button is clicked, is shown in <>. [[figure.advanced.windows.popup.popping]] .A Popup Window image::img/windows-popup.png[] [[advanced.windows.popup.target]] === Popup Window Name (Target) The target name is one of the default HTML target names ( [parameter]#_new#, [parameter]#_blank#, [parameter]#_top#, etc.) or a custom target name. How the window is exactly opened depends on the browser. Browsers that support tabbed browsing can open the window in another tab, depending on the browser settings. [[advanced.windows.popup.url]] === URL and Session The URL path for a popup window UI is by default determined from the UI class name, by prefixig it with " [literal]#++popup/++#". For example, for the example UI giver earlier, the URL would be [literal]#++/book-examples/book/popup/MyPopupUI++#. [[advanced.windows.popup-closing]] == Closing Popup Windows Besides closing popup windows from a native window close button, you can close them programmatically by calling the JavaScript [methodname]#close()# method as follows. [source, java] ---- public class MyPopup extends UI { @Override protected void init(VaadinRequest request) { setContent(new Button("Close Window", event -> {// Java 8 // Close the popup JavaScript.eval("close()"); // Detach the UI from the session getUI().close(); })); } } ---- 97ccf2d8197d176a0813707c7'>treecommitdiffstats
path: root/server/src/main/java/com/vaadin/ui/PopupView.java
blob: 632f17690669097def152837d4d16919395958a3 (plain) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415

/*
 * Copyright 2000-2016 Vaadin Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.vaadin.ui;

import java.io.Serializable;
import java.lang.reflect.Method;
import java.util.Collections;
import java.util.Iterator;

import org.jsoup.nodes.Element;
import org.jsoup.nodes.Node;
import org.jsoup.parser.Tag;

import com.vaadin.shared.Registration;
import com.vaadin.shared.ui.popupview.PopupViewServerRpc;
import com.vaadin.shared.ui.popupview.PopupViewState;
import com.vaadin.ui.declarative.DesignContext;

/**
 *
 * A component for displaying a two different views to data. The minimized view
 * is normally used to render the component, and when it is clicked the full
 * view is displayed on a popup. The inner class {@link PopupView.Content} is
 * used to deliver contents to this component.
 *
 * @author Vaadin Ltd.
 */
@SuppressWarnings("serial")
public class PopupView extends AbstractComponent implements HasComponents {

    private Content content;
    private Component visibleComponent;

    private static final Method POPUP_VISIBILITY_METHOD;
    static {
        try {
            POPUP_VISIBILITY_METHOD = PopupVisibilityListener.class
                    .getDeclaredMethod("popupVisibilityChange",
                            PopupVisibilityEvent.class);
        } catch (final java.lang.NoSuchMethodException e) {
            // This should never happen
            throw new java.lang.RuntimeException(
                    "Internal error finding methods in PopupView");
        }
    }

    private final PopupViewServerRpc rpc = this::setPopupVisible;

    /* Constructors */

    /**
     * This is an internal constructor. Use
     * {@link PopupView#PopupView(String, Component)} instead.
     *
     * @since 7.5.0
     */
    @Deprecated
    public PopupView() {
        registerRpc(rpc);
        setHideOnMouseOut(true);
        setContent(createContent("", new Label("")));
    }

    /**
     * A simple way to create a PopupPanel. Note that the minimal representation
     * may not be dynamically updated, in order to achieve this create your own
     * Content object and use {@link PopupView#PopupView(Content)}.
     *
     * @param small
     *            the minimal textual representation as HTML
     * @param large
     *            the full, Component-type representation
     */
    public PopupView(final java.lang.String small, final Component large) {
        this(createContent(small, large));
    }

    /**
     * Creates a PopupView through the PopupView.Content interface. This allows
     * the creator to dynamically change the contents of the PopupView.
     *
     * @param content
     *            the PopupView.Content that contains the information for this
     */
    public PopupView(PopupView.Content content) {
        this();
        setContent(content);
    }

    /**
     * Creates a Content from given text representation and popup content.
     *
     * @since 7.5.0
     *
     * @param minimizedValue
     *            text representation when popup is hidden
     * @param popupContent
     *            popup content
     * @return content with given data
     */
    protected static Content createContent(final String minimizedValue,
            final Component popupContent) {
        return new Content() {
            @Override
            public String getMinimizedValueAsHTML() {
                return minimizedValue;
            }

            @Override
            public Component getPopupComponent() {
                return popupContent;
            }
        };
    }

    /**
     * This method will replace the current content of the panel with a new one.
     *
     * @param newContent
     *            PopupView.Content object containing new information for the
     *            PopupView
     * @throws IllegalArgumentException
     *             if the method is passed a null value, or if one of the
     *             content methods returns null
     */
    public void setContent(PopupView.Content newContent)
            throws IllegalArgumentException {
        if (newContent == null) {
            throw new IllegalArgumentException("Content must not be null");
        }
        content = newContent;
        markAsDirty();
    }

    /**
     * Returns the content-package for this PopupView.
     *
     * @return the PopupView.Content for this object or null
     */
    public PopupView.Content getContent() {
        return content;
    }

    /**
     * Set the visibility of the popup. Does not hide the minimal
     * representation.
     *
     * @param visible
     */
    public void setPopupVisible(boolean visible) {
        if (isPopupVisible() != visible) {
            if (visible) {
                visibleComponent = content.getPopupComponent();
                if (visibleComponent == null) {
                    throw new java.lang.IllegalStateException(
                            "PopupView.Content did not return Component to set visible");
                }
                if (visibleComponent.getParent() != null) {
                    // If the component already has a parent, try to remove it
                    AbstractSingleComponentContainer
                            .removeFromParent(visibleComponent);
                }
                visibleComponent.setParent(this);
            } else {
                if (equals(visibleComponent.getParent())) {
                    visibleComponent.setParent(null);
                }
                visibleComponent = null;
            }
            fireEvent(new PopupVisibilityEvent(this));
            markAsDirty();
        }
    }

    @Override
    public void beforeClientResponse(boolean initial) {
        super.beforeClientResponse(initial);
        String html = content.getMinimizedValueAsHTML();
        if (html == null) {
            html = "";
        }
        getState().html = html;
    }

    /**
     * Return whether the popup is visible.
     *
     * @return true if the popup is showing
     */
    public boolean isPopupVisible() {
        return visibleComponent != null;
    }

    /**
     * Check if this popup will be hidden when the user takes the mouse cursor
     * out of the popup area.
     *
     * @return true if the popup is hidden on mouse out, false otherwise
     */
    public boolean isHideOnMouseOut() {
        return getState(false).hideOnMouseOut;
    }

    /**
     * Should the popup automatically hide when the user takes the mouse cursor
     * out of the popup area? If this is false, the user must click outside the
     * popup to close it. The default is true.
     *
     * @param hideOnMouseOut
     *
     */
    public void setHideOnMouseOut(boolean hideOnMouseOut) {
        getState().hideOnMouseOut = hideOnMouseOut;
    }

    /*
     * Methods inherited from AbstractComponentContainer. These are unnecessary
     * (but mandatory). Most of them are not supported in this implementation.
     */

    /**
     * This class only contains other components when the popup is showing.
     *
     * @see com.vaadin.ui.ComponentContainer#getComponentIterator()
     */
    @Override
    public Iterator<Component> iterator() {
        if (visibleComponent != null) {
            return Collections.singletonList(visibleComponent).iterator();
        } else {
            return Collections.<Component> emptyList().iterator();
        }
    }

    /**
     * Gets the number of contained components.
     *
     * @return the number of contained components (zero or one)
     */
    public int getComponentCount() {
        return (visibleComponent != null ? 1 : 0);
    }

    @Override
    public void readDesign(Element design, DesignContext designContext) {

        // Read content first to avoid NPE when setting popup visible
        Component popupContent = null;
        String minimizedValue = "";
        for (Node childNode : design.childNodes()) {
            if (childNode instanceof Element) {
                Element child = (Element) childNode;
                if (child.tagName().equals("popup-content")) {
                    popupContent = designContext.readDesign(child.child(0));
                } else {
                    minimizedValue += child.toString();
                }
            } else {
                minimizedValue += childNode.toString();
            }
        }
        setContent(createContent(minimizedValue.trim(), popupContent));

        super.readDesign(design, designContext);
    }

    @Override
    public void writeDesign(Element design, DesignContext designContext) {
        super.writeDesign(design, designContext);

        Element popupContent = new Element(Tag.valueOf("popup-content"), "");
        popupContent.appendChild(
                designContext.createElement(content.getPopupComponent()));

        String minimizedHTML = content.getMinimizedValueAsHTML();
        if (minimizedHTML != null && !minimizedHTML.isEmpty()) {
            design.append(minimizedHTML);
        }
        design.appendChild(popupContent);
    }

    @Override
    protected PopupViewState getState() {
        return (PopupViewState) super.getState();
    }

    @Override
    protected PopupViewState getState(boolean markAsDirty) {
        return (PopupViewState) super.getState(markAsDirty);
    }

    /**
     * Used to deliver customized content-packages to the PopupView. These are
     * dynamically loaded when they are redrawn. The user must take care that
     * neither of these methods ever return null.
     */
    public interface Content extends Serializable {

        /**
         * This should return a small view of the full data.
         *
         * @return value in HTML format
         */
        public String getMinimizedValueAsHTML();

        /**
         * This should return the full Component representing the data
         *
         * @return a Component for the value
         */
        public Component getPopupComponent();
    }

    /**
     * Add a listener that is called whenever the visibility of the popup is
     * changed.
     *
     * @see PopupVisibilityListener
     * @see PopupVisibilityEvent
     *
     * @param listener
     *            the listener to add, not null
     * @return a registration object for removing the listener
     */
    public Registration addPopupVisibilityListener(
            PopupVisibilityListener listener) {
        return addListener(PopupVisibilityEvent.class, listener,
                POPUP_VISIBILITY_METHOD);
    }

    /**
     * Removes a previously added listener, so that it no longer receives events
     * when the visibility of the popup changes.
     *
     * @param listener
     *            the listener to remove
     * @see PopupVisibilityListener
     * @see #addPopupVisibilityListener(PopupVisibilityListener)
     *
     * @deprecated As of 8.0, replaced by {@link Registration#remove()} in the
     *             registration object returned from
     *             {@link #addPopupVisibilityListener(PopupVisibilityListener)}.
     */
    @Deprecated
    public void removePopupVisibilityListener(
            PopupVisibilityListener listener) {
        removeListener(PopupVisibilityEvent.class, listener,
                POPUP_VISIBILITY_METHOD);
    }

    /**
     * This event is received by the PopupVisibilityListeners when the
     * visibility of the popup changes. You can get the new visibility directly
     * with {@link #isPopupVisible()}, or get the PopupView that produced the
     * event with {@link #getPopupView()}.
     *
     */
    public static class PopupVisibilityEvent extends Event {

        public PopupVisibilityEvent(PopupView source) {
            super(source);
        }

        /**
         * Get the PopupView instance that is the source of this event.
         *
         * @return the source PopupView
         */
        public PopupView getPopupView() {
            return (PopupView) getSource();
        }

        /**
         * Returns the current visibility of the popup.
         *
         * @return true if the popup is visible
         */
        public boolean isPopupVisible() {
            return getPopupView().isPopupVisible();
        }
    }

    /**
     * Defines a listener that can receive a PopupVisibilityEvent when the
     * visibility of the popup changes.
     *
     */
    @FunctionalInterface
    public interface PopupVisibilityListener extends Serializable {
        /**
         * Pass to {@link PopupView.PopupVisibilityEvent} to start listening for
         * popup visibility changes.
         *
         * @param event
         *            the event
         *
         * @see PopupVisibilityEvent
         * @see PopupView#addPopupVisibilityListener(PopupVisibilityListener)
         */
        public void popupVisibilityChange(PopupVisibilityEvent event);
    }
}