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
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
|
---
title: Embedding UIs in Web Pages
order: 2
layout: page
---
[[advanced.embedding]]
= 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 [literal]#++<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 [literal]#++<iframe>++#
element. Both of these methods have advantages and disadvantages. One
disadvantage of the [literal]#++<iframe>++# method is that the size of the
[literal]#++<iframe>++# element is not flexible according to the content while
the [literal]#++<div>++# method allows such flexibility. The following sections
look closer into these two embedding methods.
[[advanced.embedding.div]]
== Embedding Inside a [literal]#++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 [classname]#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
* Call the [filename]#vaadinBootstrap.js# file
* Define the [literal]#++<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.
ifdef::web[]
[[advanced.embedding.div.head]]
=== The Head Matter
The HTML page in which the Vaadin UI is embedded should be a valid HTML 5
document. 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.
[subs="normal"]
----
<!DOCTYPE html>
<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>[replaceable]#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/[replaceable]#reindeer#/favicon.ico" />
<link rel="icon" type="image/vnd.microsoft.icon"
href="/VAADIN/themes/[replaceable]#reindeer#/favicon.ico" />
</head>
----
endif::web[]
ifdef::web[]
[[advanced.embedding.div.body]]
=== The Body Matter
The page content must include some Vaadin-related definitions before you can
embed Vaadin UIs in it.
The [filename]#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.
[subs="normal"]
----
<body>
<script type="text/javascript"
src="[replaceable]#./#VAADIN/vaadinBootstrap.js"></script>
----
The bootstrap script is served by the Vaadin servlet from inside the
[filename]#vaadin-server# JAR.
endif::web[]
ifdef::web[]
[[advanced.embedding.div.div]]
=== UI Placeholder Element
A Vaadin UI is embedded in a placeholder [literal]#++<div>++# element. It should
have the following features:
* The [literal]#++<div>++# element must have an [literal]#++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 [literal]#++v-app++# style class.
* it should have a nested [literal]#++<div>++# element with [literal]#++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 [literal]#++<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:
[subs="normal"]
----
<div style="[replaceable]#width: 300px; border: 2px solid green;#"
id="helloworldui" class="v-app">
<div class="v-app-loading"></div>
<noscript>[replaceable]#You have to enable javascript in your browser to#
[replaceable]#use an application built with Vaadin.#</noscript>
</div>
----
endif::web[]
ifdef::web[]
[[advanced.embedding.div.init]]
=== Initializing the UI
The UI is loaded by calling the [literal]#++initApplication()++# method for the
[literal]#++vaadin++# object defined in the bootstrap script. Before calling it,
you should check that the bootstrap script was loaded properly.
[subs="normal"]
----
<script type="text/javascript">//<!\[CDATA[
if (!window.vaadin)
alert("[replaceable]#Failed to load the bootstrap JavaScript:#"+
"[replaceable]#VAADIN/vaadinBootstrap.js#");
----
The [literal]#++initApplication()++# takes two parameters. The first parameter
is the UI identifier, exactly as given as the [literal]#++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:
[parameter]#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. A
trailing slash may be needed in some cases.
+
Notice that this parameter is not included in the loader page generated by the
servlet, because in that case, it can default to the current URL.
[parameter]#serviceUrl#:: This is used for server requests after initial loading and should be same as for
[parameter]#browserDetailsUrl#. The two parameters are redundant and either may
be removed in
future.+
//Bug
#10122
[parameter]#widgetset#:: This should be the exact class name of the widget set for the UI, that is, without the [filename]#.gwt.xml# file name extension. If the UI has no custom widget set, you can use the [classname]#com.vaadin.DefaultWidgetSet#.
[parameter]#theme#:: Name of the theme, such as one of the built-in themes ( [literal]#++reindeer++#, [literal]#++runo++#, or [literal]#++chameleon++#) or a custom theme. It must exist under the [filename]#VAADIN/themes# folder.
[parameter]#versionInfo#:: This parameter is itself an associative map that can contain two parameters: [parameter]#vaadinVersion# contains the version number of the Vaadin version used by the application. The [parameter]#applicationVersion# parameter contains the version of the particular application. The contained parameters are optional, but the [parameter]#versionInfo# parameter itself is not.
[parameter]#vaadinDir#:: Relative path to the [filename]#VAADIN# directory. It is relative to the URL of the embedding page.
[parameter]#heartbeatInterval#:: The [parameter]#hearbeatInterval# parameter defines the frequency of the keep-alive hearbeat for the UI in seconds, as described in <<dummy/../../../framework/application/application-lifecycle#application.lifecycle.ui-expiration,"UI Expiration">>.
[parameter]#debug#:: The parameter defines whether the debug window, as described in <<dummy/../../../framework/advanced/advanced-debug#advanced.debug,"Debug Mode and Window">>, is enabled.
[parameter]#standalone#:: This parameter should be [parameter]#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.
[parameter]#authErrMsg#,[parameter]#comErrMsg#, and[parameter]#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: [parameter]#message#, which should contain the error text in HTML, and [parameter]#caption#, which should be the error caption.
For example:
[subs="normal"]
----
vaadin.initApplication("[replaceable]#helloworldui#", {
"browserDetailsUrl": "[replaceable]#helloworld#/",
"serviceUrl": "[replaceable]#helloworld#/",
"widgetset": "[replaceable]#com.example.MyWidgetSet#",
"theme": "[replaceable]#mytheme#",
"versionInfo": {"vaadinVersion": "[replaceable]#8.1.6#"},
"vaadinDir": "[replaceable]#VAADIN/#",
"heartbeatInterval": [replaceable]#300#,
"debug": [replaceable]#true#,
"standalone": false,
"authErrMsg": {
"message": "[replaceable]#Take note of any unsaved data, "+ "and <u>click here<\/u> to continue.#",
"caption": "Authentication problem"
},
"comErrMsg": {
"message": "[replaceable]#Take note of any unsaved data, "+ "and <u>click here<\/u> to continue.#",
"caption": "Communication problem"
},
"sessExpMsg": {
"message": "[replaceable]#Take note of any unsaved data, "+ "and <u>click here<\/u> to continue.#",
"caption": "Session Expired"
}
});//]]>
</script>
----
Notice that many of the parameters are normally deployment parameters, specified
in the deployment descriptor, as described in
<<dummy/../../../framework/application/application-environment#application.environment.parameters,"Other
Servlet Configuration Parameters">>.
endif::web[]
ifdef::web[]
[[advanced.embedding.div.summary]]
=== Summary of Div Embedding
Below is a complete example of embedding an UI in a [literal]#++<div>++#
element.
[source, html]
----
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html>
<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>Embedding a Vaadin Application in HTML 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>
<body>
<!-- Loads the Vaadin widget set, etc. -->
<script type="text/javascript"
src="VAADIN/vaadinBootstrap.js"></script>
<h1>Embedding a Vaadin UI</h1>
<p>This is a static web page that contains an embedded Vaadin
application. It's here:</p>
<!-- So here comes the div element in which the Vaadin -->
<!-- application is embedded. -->
<div style="width: 300px; border: 2px solid green;"
id="helloworld" class="v-app">
<!-- Optional placeholder for the loading indicator -->
<div class=" v-app-loading"></div>
<!-- Alternative fallback text -->
<noscript>You have to enable javascript in your browser to
use an application built with Vaadin.</noscript>
</div>
<script type="text/javascript">//<![CDATA[
if (!window.vaadin)
alert("Failed to load the bootstrap JavaScript: "+
"VAADIN/vaadinBootstrap.js");
/* The UI Configuration */
vaadin.initApplication("helloworld", {
"browserDetailsUrl": "helloworld/",
"serviceUrl": "helloworld/",
"widgetset": "com.example.MyWidgetSet",
"theme": "mytheme",
"versionInfo": {"vaadinVersion": "8.1.6"},
"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.",
"caption": "Session Expired"
}
});//]] >
</script>
<p>Please view the page source to see how embedding works.</p>
</body>
</html>
----
endif::web[]
[[advanced.embedding.iframe]]
== Embedding Inside an [literal]#++iframe++# Element
Embedding a Vaadin UI inside an [literal]#++<iframe>++# element is even easier
than the method described above, as it does not require definition of any Vaadin
specific definitions.
You can embed an UI with an element such as the following:
[subs="normal"]
----
<iframe src="[replaceable]#/myapp/myui#"></iframe>
----
The [literal]#++<iframe>++# elements have several downsides for embedding. One
is that their size of is not flexible depending on the content of the frame, but
the content must be flexible to accommodate in the frame. You can set the size
of an [literal]#++<iframe>++# element with [literal]#++height++# and
[literal]#++width++# attributes. Other issues arise from themeing and
communication with the frame content and the rest of the page.
Below is a complete example of using the [literal]#++<iframe>++# to embed two
applications in a web page.
[source, html]
----
<!DOCTYPE html>
<html>
<head>
<title>Embedding in IFrame</title>
</head>
<body style="background: #d0ffd0;">
<h1>This is a HTML page</h1>
<p>Below are two Vaadin applications embedded inside
a table:</p>
<table align="center" border="3">
<tr>
<th>The Calculator</th>
<th>The Color Picker</th>
</tr>
<tr valign="top">
<td>
<iframe src="/vaadin-examples/Calc" height="200"
width="150" frameborder="0"></iframe>
</td>
<td>
<iframe src="/vaadin-examples/colorpicker"
height="330" width="400"
frameborder="0"></iframe>
</td>
</tr>
</table>
</body>
</html>
----
The page will look as shown in <<figure.embedding.iframe>> below.
[[figure.embedding.iframe]]
.Vaadin Applications Embedded Inside IFrames
image::img/embedding3.png[]
You can embed almost anything in an iframe, which essentially acts as a browser
window. However, this creates various problems. The iframe must have a fixed
size, inheritance of CSS from the embedding page is not possible, and neither is
interaction with JavaScript, which makes mashups impossible, and so on. Even
bookmarking with URI fragments will not work.
Note also that websites can forbid iframe embedding by specifying an
[literal]#++X-Frame-Options: SAMEORIGIN++# header in the HTTP response.
ifdef::web[]
[[advanced.embedding.xs]]
== Cross-Site Embedding with the Vaadin XS Add-on
__The XS add-on is currently not available for Vaadin 7.__
In the previous sections, we described the two basic methods for embedding
Vaadin applications: in a [literal]#++<div>++# element and in an
[literal]#++<iframe>++#. One problem with div embedding is that it does not work
between different Internet domains, which is a problem if you want to have your
website running in one server and your Vaadin application in another. The
security model in browsers effectively prevents such cross-site embedding of
Ajax applications by enforcing the __same origin policy__ for XmlHttpRequest
calls, even if the server is running in the same domain but different port.
While iframe is more permissive, allowing embedding almost anything in anywhere,
it has many disadvantanges, as described earlier.
The Vaadin XS (Cross-Site) add-on works around the limitation in div embedding
by using JSONP-style communication instead of the standard XmlHttpRequests.
Embedding is done simply with:
[source, html]
----
<script src="http://demo.vaadin.com/xsembed/getEmbedJs"
type="text/javascript"></script>
----
This includes an automatically generated embedding script in the page, thereby
making embedding effortless.
This assumes that the main layout of the application has undefined height. If
the height is 100%, you have to wrap it inside an element with a defined height.
For example:
[source, html]
----
<div style="height: 500px;">
<script src="http://demo.vaadin.com/xsembed/getEmbedJs"
type="text/javascript"></script>
</div>
----
It is possible to restrict where the application can be embedded by using a
whitelist. The add-on also encrypts the client-server communication, which is
more important for embedded applications than usual.
You can get the Vaadin XS add-on from Vaadin Directory. It is provided as a Zip
package. Download and extract the installation package to a local folder.
Instructions for installation and further information is given in the
[filename]#README.html# file in the package.
Some restrictions apply. You can have only one embedded application in one page.
Also, some third-party libraries may interfere with the communication. Other
notes are given in the README.
endif::web[]
|