Embedding Web-Components

Browser Widget Overview

Using the SWT/RWT
Browser
widget, it is possible to embed HTML pages, simple JavaScript
Applications, Flash-Objects, Java-Applets or any other web component seamlessly into your
RAP (or SWT) application.

In RAP, any HTML document (including JavaScript) placed in a Browser widget
will end up in an iframe element. You can call JavaScript from Java by using
evaluate,
and vice versa using the
BrowserFunctionBrowserFunction
class.
It's recommended
to always use evaluate instead of
execute,
since it throws an exception if the JavaScript execution fails.
Before you can use evaluate, you must wait until the document is fully loaded,
using either a
ProgressListener
or a BrowserFunction.

RAP-specific notes

Alternatives

The Browser-Widget is suitable for embedding complete HTML documents and very simple web apps.
When you only want to display a few lines of rich/formatted text, use the more lightweight
markup feature instead. Also, keep in mind that each call
to a BrowserFunction or to evaluate creates an HTTP request.
To reduce the resulting traffic you can try combining subsequent call, but if you want to embed
a web app/object that requires a lot of client-server communication, consider using
the more efficient
RAP Remote API.
Note, however, that
both, markup and the JavaScript Remote API, are features of the RAP web client,
and are not available in SWT or on other clients.
If SWT-Support is a requirement, use the Brower widget in any case.

Browser security restrictions

Since the browser widget is based on the HTML iframe element,
all security restrictions regarding cross-frame-scripting apply. This means for
execute, evaluate and BrowserFunction to work,
the document loaded in the browser widget has to come from the
same domain and port that the RAP application is loaded from. This is automatically given
if the
setText
method is used, or the file is registered as a static resource.

Resources

It's important to decide how your resources (HTML, JavaScript, CSS and image files) are
provided to the browser widget. If you use only a moderate amount of HTML with inlined
JavaScript and/or CSS (and no images), or your non-HTML resources can be loaded from
a different HTTP-server, it will suffice to use the
setText
method of the browser
widget. This code would then also run in an SWT application. However, when using
setText, the client browser can not cache the loaded document, so each new instance has
to load and parse it again.
A good example of a custom widget using this strategy is the
Browser-based
Google Maps widget. It runs in SWT and in RAP.
When a not all resources can be inlined in the HTML file (like images), and they are to be
provided by the RAP application itself, it is necessary to register them as
static resources.

Limitations in JEE Mode

When using the
JEE compatibilityOperationMode
(the default for non-workbench based applications), then
the executeScript and evaluate methods will not block program
execution.
Like with dialogs, a workaround is possible using the class
BrowserUtil,
which lets you register a callback to receive the results of the evaluate
call. However, this pattern makes implementing a traditional "getter" impossible.
In SWT compatibility mode you can write: