path: root/documentation/advanced/advanced-embedding.asciidoc

---
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
* Include a GWT history frame in the page
* 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"]
----
&lt;!DOCTYPE html&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;meta http-equiv="Content-Type"
          content="text/html; charset=UTF-8" /&gt;
    &lt;meta http-equiv="X-UA-Compatible"
          content="IE=9;chrome=1" /&gt;

    &lt;title&gt;[replaceable]#This is my Embedding Page#&lt;/title&gt;
  
    &lt;!-- Set up the favicon from the Vaadin theme --&gt;
    &lt;link rel="shortcut icon" type="image/vnd.microsoft.icon"
          href="/VAADIN/themes/[replaceable]#reindeer#/favicon.ico" /&gt;
    &lt;link rel="icon" type="image/vnd.microsoft.icon"
             href="/VAADIN/themes/[replaceable]#reindeer#/favicon.ico" /&gt; 
  &lt;/head&gt;
----
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"]
----
&lt;body&gt;
  &lt;script type="text/javascript"
          src="[replaceable]#./#VAADIN/vaadinBootstrap.js"&gt;&lt;/script&gt;
----
The bootstrap script is served by the Vaadin servlet from inside the
[filename]#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.


[source, html]
----
  <iframe tabindex="-1" id="__gwt_historyFrame"
          style="position: absolute; width: 0; height: 0;
                 border: 0; overflow: hidden"
          src="javascript:false"></iframe>
----

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"]
----
&lt;div style="[replaceable]#width: 300px; border: 2px solid green;#"
     id="helloworldui" class="v-app"&gt;
  &lt;div class="v-app-loading"&gt;&lt;/div&gt;
  &lt;noscript&gt;[replaceable]#You have to enable javascript in your browser to#
            [replaceable]#use an application built with Vaadin.#&lt;/noscript&gt;
&lt;/div&gt;
----
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"]
----
&lt;script type="text/javascript"&gt;//&lt;![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]#7.0.0#"},
      "vaadinDir": "[replaceable]#VAADIN/#",
      "heartbeatInterval": [replaceable]#300#,
      "debug": [replaceable]#true#,
      "standalone": false,
      "authErrMsg": {
          "message": "[replaceable]#Take note of any unsaved data, "+ "and &lt;u&gt;click here&lt;\/u&gt; to continue.#",
          "caption": "Authentication problem"
      },
      "comErrMsg": {
          "message": "[replaceable]#Take note of any unsaved data, "+ "and &lt;u&gt;click here&lt;\/u&gt; to continue.#",
          "caption": "Communication problem"
      },
      "sessExpMsg": {
          "message": "[replaceable]#Take note of any unsaved data, "+ "and &lt;u&gt;click here&lt;\/u&gt; to continue.#",
          "caption": "Session Expired"
      }
  });//]]&gt;
&lt;/script&gt;
----
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>

  <!-- GWT requires an invisible history frame. It is   -->
  <!-- needed for page/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>  

  <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": "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.",
	        "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"]
----
&lt;iframe src="[replaceable]#/myapp/myui#"&gt;&lt;/iframe&gt;
----
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[]