vaadin-framework/documentation/components/components-embedded.asciidoc

---
title: Embedded Resources
order: 34
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 alternative 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.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, and browser frames which you can embed with the
specialized components.

Display 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 Framework. 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.