Файл: book-of-vaadin.pdf

Advanced Web Application Topics

11.1. 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 Window component, which is a floating panel or sub-window inside a page, as described in Section 6.7, “Sub-Windows”.

•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 Section 11.2, “Embedding UIs in Web Pages”.

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 VaadinSession object, as described in Section 4.7.3, “User Session”. 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 Section 4.7.4, “Loading a UI”.

Because of the special nature of AJAX applications, use of multiple windows uses require some caveats.

11.1.1. Opening Popup Windows

Popup windows are native browser windows or tabs opened by user interaction with an existing window. Due to browser security reasons, it is made incovenient 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 BrowserWindowOpener component extension, which causes the browser to open a window or tab when the component is clicked.

The Popup Window UI

A popup Window displays an 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:

@Theme("book-examples")

public static class MyPopupUI extends UI { @Override

protected void init(VaadinRequest request) { getPage().setTitle("Popup Window");

Advanced Web Application Topics

// 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);

}

}

Popping It Up

A popup window is opened using the 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 setFeatures(). It takes as its parameter a semicolon-separated list of window features, as defined in the HTML specification.

status=0|1

Whether the status bar at the bottom of the window should be enabled.

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=value

Specifies the height of the window in pixels.

width=value

Specifies the width of the window in pixels.

For example:

//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 11.1, “A Popup Window”.

Advanced Web Application Topics

Figure 11.1. A Popup Window

Popup Window Name (Target)

The target name is one of the default HTML target names (_new, _blank, _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.

URL and Session

The URL path for a popup window UI is by default determined from the UI class name, by prefixig it with "popup/". For example, for the example UI giver earlier, the URL would be

/book-examples/book/popup/MyPopupUI.

11.2. Embedding UIs in Web Pages

Many web sites are not all Vaadin, but Vaadin UIs are used only for specific functionalities. In practice, many web applications are a mixture of dynamic web pages, such as JSP, and Vaadin UIs embedded in such pages.

Embedding Vaadin UIs in web pages is easy and there are several different ways to embed them. One is to have a <div> placeholder for the UI and load the Vaadin Client-Side Engine with some simple JavaScript code. Another method is even easier, which is to simply use the <iframe> element. Both of these methods have advantages and disadvantages. One disadvantage of the <iframe> method is that the size of the <iframe> element is not flexible according to the content while the <div> method allows such flexibility. The following sections look closer into these two embedding methods. Additionally, the Vaadin XS add-on allows embedding Vaadin UIs in websites running in another server.

11.2.1. Embedding Inside a div Element

You can embed one or more Vaadin UIs inside a web page with a method that is equivalent to loading the initial page content from the Vaadin servlet in a non-embedded UI. Normally, the VaadinServlet generates an initial page that contains the correct parameters for the specific UI. You can easily configure it to load multiple Vaadin UIs in the same page. They can have different widget sets and different themes.

Embedding an UI requires the following basic tasks:

• Set up the page header

Advanced Web Application Topics

•Include a GWT history frame in the page

•Call the vaadinBootstrap.js file

•Define the <div> element for the UI

•Configure and initialize the UI

Notice that you can view the loader page for the UI easily by opening the UI in a web browser and viewing the HTML source code of the page. You could just copy and paste the embedding code from the page, but some modifications and additional settings are required, mainly related to the URLs that have to be made relative to the page instead of the servlet URL.

The DIV embedding API is about to change soon after printing this book edition. A tutorial that describes the feature should be made available at the Vaadin website.

The Head Matter

The HTML page in which the Vaadin UI is embedded should be a valid XHTML document, as defined in the document type.The content of the head element is largely up to you.The character encoding must be UTF-8. Some meta declarations are necessary for compatibility. You can also set the page favicon in the head element.

<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

<meta http-equiv="X-UA-Compatible" content="IE=9;chrome=1" />

<title>This is my Embedding Page</title>

<!-- Set up the favicon from the Vaadin theme -->

<link rel="shortcut icon" type="image/vnd.microsoft.icon" href="/VAADIN/themes/reindeer/favicon.ico" />

<link rel="icon" type="image/vnd.microsoft.icon" href="/VAADIN/themes/reindeer/favicon.ico" />

</head>

The Body Matter

The page content must include some Vaadin-related definitions before you can embed Vaadin UIs in it.

The vaadinBootstrap.js script makes definitions for starting up the UI. It must be called before initializing the UI. The source path must be relative to the path of the embedding page.

<body>

<script type="text/javascript" src="./VAADIN/vaadinBootstrap.js"></script>

The bootstrap script is served by the Vaadin servlet from inside the vaadin-server JAR.

Vaadin, or more precisely GWT, requires an invisible history frame, which is used for tracking the page or fragment history in the browser.

<iframe tabindex="-1" id="__gwt_historyFrame" style="position: absolute; width: 0; height: 0;

border: 0; overflow: hidden" src="javascript:false"></iframe>

Advanced Web Application Topics

UI Placeholder Element

A Vaadin UI is embedded in a placeholder <div> element. It should have the following features:

•The <div> element must have an id attribute, which must be a unique ID in the page, normally something that identifies the servlet of the UI uniquely.

•It must have at least the v-app style class.

•it should have a nested <div> element with v-app-loading style class. This is a placeholder for the loading indicator that is displayed while the UI is being loaded.

•It should also contain a <noscript> element that is shown if the browser does not support JavaScript or it has been disabled. The content of the element should instruct the use to enable JavaScript in the browser.

The placeholder element can include style settings, typically a width and height. If the sizes are not defined, the UI will have an undefined size in the particular dimension, which must be in accordance with the sizing of the UI components.

For example:

<div style="width: 300px; border: 2px solid green;" id="helloworldui" class="v-app">

<div class="v-app-loading"></div>

<noscript>You have to enable javascript in your browser to use an application built with Vaadin.</noscript>

</div>

Initializing the UI

The UI is loaded by calling the initApplication() method for the vaadin object defined in the bootstrap script. Before calling it, you should check that the bootstrap script was loaded properly.

<script type="text/javascript">//<![CDATA[ if (!window.vaadin)

alert("Failed to load the bootstrap JavaScript:"+ "VAADIN/vaadinBootstrap.js");

The initApplication() takes two parameters. The first parameter is the UI identifier, exactly as given as the id attribute of the placeholder element. The second parameter is an associative map that contains parameters for the UI.

The map must contain the following items:

browserDetailsUrl

This should be the URL path (relative to the embedding page) to the Vaadin servlet of the UI. It is used by the bootstrap to communicate browser details.

Notice that this parameter not included in the loader page generated by the servlet, as in that case it can default to the current URL.

widgetset

This should be the exact class name of the widget set for the UI, that is, without the

.gwt.xml file name extension. If the UI has no custom widget set, you can use the com.vaadin.DefaultWidgetSet.

Advanced Web Application Topics

theme

Name of the theme, such as one of the built-in themes (reindeer, runo, or chameleon) or a custom theme. It must exist under the VAADIN/themes folder.

versionInfo

This parameter is itself an associative map that can contain two parameters: vaadinVersion contains the version number of the Vaadin version used by the application.The applicationVersion parameter contains the version of the particular application. The contained parameters are optional, but the versionInfo parameter itself is not.

vaadinDir

Relative path to the VAADIN directory. It is relative to the URL of the embedding page.

heartbeatInterval

The hearbeatInterval parameter defines the frequency of the keep-alive hearbeat for the UI in seconds, as described in Section 4.7.5, “UI Expiration”.

debug

The parameter defines whether the debug window, as described in Section 11.3, “Debug and Production Mode”, is enabled.

standalone

This parameter should be false when embedding. The parameter defines whether the UI is rendered on its own in the browser window or in some context. A standalone UI may do things that might interfere with other parts of the page, such as change the page title and request focus when it is loaded. When embedding, the UI is not standalone.

authErrMsg, comErrMsg, and sessExpMsg

These three parameters define the client-side error messages for authentication error, communication error, and session expiration, respectively. The parameters are associative maps themselves and must contain two key-value pairs: message, which should contain the error text in HTML, and caption, which should be the error caption.

For example:

vaadin.initApplication("helloworldui", { "browserDetailsUrl": "helloworld", "widgetset": "com.example.MyWidgetSet", "theme": "mytheme",

"versionInfo": {"vaadinVersion": "7.0.0"}, "vaadinDir": "VAADIN/", "heartbeatInterval": 300,

"debug": true, "standalone": false, "authErrMsg": {

"message": "Take note of any unsaved data, "+ "and <u>click here<\/u> to continue.",

"caption": "Authentication problem"

}, "comErrMsg": {

"message": "Take note of any unsaved data, "+ "and <u>click here<\/u> to continue.",

"caption": "Communication problem"

}, "sessExpMsg": {

"message": "Take note of any unsaved data, "+ "and <u>click here<\/u> to continue.",