Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 205 insertions, 0 deletions

diff --git a/documentation/components/components-embedded.asciidoc b/documentation/components/components-embedded.asciidoc
new file mode 100644
index 0000000000..bea83971a8
--- /dev/null
+++ b/documentation/components/components-embedded.asciidoc
@@ -0,0 +1,205 @@
+---
+title: Embedded Resources
+order: 33
+layout: page
+---
+
+[[components.embedded]]
+= Embedded Resources
+
+You can embed images in Vaadin UIs with the [classname]#Image# component, Adobe
+Flash graphics with [classname]#Flash#, and other web content with
+[classname]#BrowserFrame#. There is also a generic [classname]#Embedded#
+component for embedding other object types. The embedded content is referenced
+as __resources__, as described in
+<<dummy/../../../framework/application/application-resources#application.resources,"Images
+and Other Resources">>.
+
+The following example displays an image as a class resource loaded with the
+class loader:
+
+
+[source, java]
+----
+Image image = new Image("Yes, logo:",
+    new ClassResource("vaadin-logo.png"));
+main.addComponent(image);
+----
+
+The caption can be given as null to disable it. An empty string displays an
+empty caption which takes a bit space. The caption is managed by the containing
+layout.
+
+You can set an altenative text for an embedded resource with
+[methodname]#setAlternateText()#, which can be shown if images are disabled in
+the browser for some reason. The text can be used for accessibility purposes,
+such as for text-to-speech generation.
+
+[[components.embedded.image]]
+== Embedded [classname]#Image#
+
+The [classname]#Image# component allows embedding an image resource in a Vaadin
+UI.
+
+
+[source, java]
+----
+// Serve the image from the theme
+Resource res = new ThemeResource("img/myimage.png");
+
+// Display the image without caption
+Image image = new Image(null, res);
+layout.addComponent(image);
+----
+
+The [classname]#Image# component has by default undefined size in both
+directions, so it will automatically fit the size of the embedded image.
+((("scroll
+bars")))
+If you want scrolling with scroll bars, you can put the image inside a
+[classname]#Panel# that has a defined size to enable scrolling, as described in
+<<dummy/../../../framework/layout/layout-panel#layout.panel.scrolling,"Scrolling
+the Panel Content">>. You can also put it inside some other component container
+and set the [literal]#++overflow: auto++# CSS property for the container element
+in a theme to enable automatic scrollbars. (((overflow CSS
+property)))
+
+[[components.embedded.image.generated]]
+=== Generating and Reloading Images
+
+You can also generate the image content dynamically using a
+[classname]#StreamResource#, as described in
+<<dummy/../../../framework/application/application-resources#application.resources.stream,"Stream
+Resources">>, or with a [classname]#RequestHandler#.
+
+If the image changes, the browser needs to reload it. Simply updating the stream
+resource is not enough. Because of how caching is handled in some browsers, you
+can cause a reload easiest by renaming the filename of the resource with a
+unique name, such as one including a timestamp. You should set cache time to
+zero with [methodname]#setCacheTime()# for the resource object when you create
+it.//BUG
+#2470.
+
+
+[source, java]
+----
+// Create the stream resource with some initial filename
+StreamResource imageResource =
+    new StreamResource(imageSource, "initial-filename.png");
+
+// Instruct browser not to cache the image
+imageResource.setCacheTime(0);
+
+// Display the image
+Image image = new Image(null, imageResource);
+----
+
+When refreshing, you also need to call [methodname]#markAsDirty()# for the
+[classname]#Image# object.
+
+
+[source, java]
+----
+// This needs to be done, but is not sufficient
+image.markAsDirty();
+
+// Generate a filename with a timestamp
+SimpleDateFormat df = new SimpleDateFormat("yyyyMMddHHmmssSSS");
+String filename = "myfilename-" + df.format(new Date()) + ".png";
+
+// Replace the filename in the resource
+imageResource.setFilename(makeImageFilename());
+----
+
+
+
+[[components.embedded.flash]]
+== Adobe [classname]#Flash# Graphics
+
+The [classname]#Flash# component allows embedding Adobe Flash animations in
+Vaadin UIs.
+
+
+[source, java]
+----
+Flash flash = new Flash(null,
+    new ThemeResource("img/vaadin_spin.swf"));
+layout.addComponent(flash);
+----
+
+You can set Flash parameters with [methodname]#setParameter()#, which takes a
+parameter's name and value as strings. You can also set the
+[parameter]#codeBase#, [parameter]#archive#, and [parameter]#standBy# attributes
+for the Flash object element in HTML.
+
+
+[[components.embedded.browserframe]]
+== [classname]#BrowserFrame#
+
+The [classname]#BrowserFrame# allows embedding web content inside an HTML
+&lt;iframe&gt; element. You can refer to an external URL with
+[classname]#ExternalResource#.
+
+As the [classname]#BrowserFrame# has undefined size by default, it is critical
+that you define a meaningful size for it, either fixed or relative.
+
+
+[source, java]
+----
+BrowserFrame browser = new BrowserFrame("Browser",
+    new ExternalResource("http://demo.vaadin.com/sampler/"));
+browser.setWidth("600px");
+browser.setHeight("400px");
+layout.addComponent(browser);
+----
+
+Notice that web pages can prevent embedding them in an &lt;iframe&gt;.
+
+
+[[components.embedded.embedded]]
+== Generic [classname]#Embedded# Objects
+
+The generic [classname]#Embedded# component allows embedding all sorts of
+objects, such as SVG graphics, Java applets, and PDF documents, in addition to
+the images, Flash graphics, and browser frames which you can embed with the
+specialized components.
+
+For example, to display a Flash animation:
+
+
+[source, java]
+----
+// A resource reference to some object
+Resource res = new ThemeResource("img/vaadin_spin.swf");
+
+// Display the object
+Embedded object = new Embedded("My Object", res);
+layout.addComponent(object);
+----
+
+Or an SVG image:
+
+
+[source, java]
+----
+// A resource reference to some object
+Resource res = new ThemeResource("img/reindeer.svg");
+
+// Display the object
+Embedded object = new Embedded("My SVG", res);
+object.setMimeType("image/svg+xml"); // Unnecessary
+layout.addComponent(object);
+----
+
+The MIME type of the objects is usually detected automatically from the filename
+extension with the [classname]#FileTypeResolver# utility in Vaadin. If not, you
+can set it explicitly with [methodname]#setMimeType()#, as was done in the
+example above (where it was actually unnecessary).
+
+Some embeddable object types may require special support in the browser. You
+should make sure that there is a proper fallback mechanism if the browser does
+not support the embedded type.
+
+
+
+