From 99d6de546c74f0eed230ea8253dda6b85109d2e7 Mon Sep 17 00:00:00 2001
From: Markus Koivisto <markus@vaadin.com>
Date: Fri, 22 Jan 2016 14:55:18 +0200
Subject: Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674
---
 documentation/advanced/advanced-embedding.asciidoc | 460 +++++++++++++++++++++
 1 file changed, 460 insertions(+)
 create mode 100644 documentation/advanced/advanced-embedding.asciidoc

(limited to 'documentation/advanced/advanced-embedding.asciidoc')

diff --git a/documentation/advanced/advanced-embedding.asciidoc b/documentation/advanced/advanced-embedding.asciidoc
new file mode 100644
index 0000000000..ca2ccd3a0e
--- /dev/null
+++ b/documentation/advanced/advanced-embedding.asciidoc
@@ -0,0 +1,460 @@
+---
+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[]
+
+
+
-- 
cgit v1.2.3