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 BrowserFunction BrowserFunction 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 compatibility OperationMode (the default for non-workbench based applications), then the executeScript and evaluate methods will not block program execution. Like with dialogs, a RAP-only method evaluate(String, BrowserCallback), is available, 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:

public String getText() {
  // assuming the web app is already fully loaded and initialized:
  return ( String )browser.evaluate( "return myWidget.getData();" );
}

In JEE compatibility mode you would have to write something like this:

public void getText( final MyCallback callback ) {
  browser.evaluate( "return myWidget.getData();", new BrowserCallback() {
    public void evaluationSucceeded( Object result ) {
      callback.handleGetText( ( String )result );
    }
    public void evaluationFailed( Exception exception ) {
      throw new RuntimeException( exception );
    }
  } );
}

If you are writing a custom widget that is supposed to feature getter that need to obtain their value using evaluate, either use the SWT compatibility mode, or consider another type of custom widget.