<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta name="copyright" content="Copyright (c) 2007, 2019 EclipseSource. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <title>Browser Widget</title>
  <link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css"/>
</head>
<body>

  <h1>Embedding Web-Components</h1>

  <h2>Browser Widget Overview</h2>

  <p>
    Using the SWT/RWT
    <em><a href="../reference/api/org/eclipse/swt/browser/Browser.html">Browser</a></em>
    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.
  </p>

  <p>
    In RAP, any HTML document (including JavaScript) placed in a <em>Browser</em> widget
    will end up in an <em>iframe</em> element. You can call JavaScript from Java by using
    <em><a href="../reference/api/org/eclipse/swt/browser/Browser.html#evaluate-java.lang.String-">evaluate</a></em>,
    and vice versa using the
    <code>BrowserFunction</code>
    <em><a href="../reference/api/org/eclipse/swt/browser/BrowserFunction.html">BrowserFunction</a></em>
    class.
    It's recommended
    to always use <em>evaluate</em> instead of
    <em><a href="../reference/api/org/eclipse/swt/browser/Browser.html#execute-java.lang.String-">execute</a></em>,
    since it throws an exception if the JavaScript execution fails.
    Before you can use <em>evaluate</em>, you must wait until the document is fully loaded,
    using either a
    <em><a href="../reference/api/org/eclipse/swt/browser/Browser.html#addProgressListener-org.eclipse.swt.browser.ProgressListener-">ProgressListener</a></em>
    or a <em>BrowserFunction</em>.
  </p>

  <h2 id="notes" >RAP-specific notes</h2>
  <h3 id="alt">Alternatives</h3>
  <p>
    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
    <a href="markup.html#markup">markup</a> feature instead. Also, keep in mind that each call
    to a <em>BrowserFunction</em> or to <em>evaluate</em> 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
    <a href="custom-widget.html#native">RAP Remote API</a>.
    <b>Note</b>, however, that
    both, markup and the JavaScript Remote API, are features of the RAP <a href="client.html">web client</a>,
    and are not available in SWT or on other clients.
    If SWT-Support is a requirement, use the <em>Brower</em> widget in any case.
  </p>

  <h3 id="security">Browser security restrictions</h3>
  <p>
    Since the browser widget is based on the HTML <em>iframe</em> element,
    all security restrictions regarding cross-frame-scripting apply. This means for
    <em>execute</em>, <em>evaluate</em> and <em>BrowserFunction</em> 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
    <em><a href="../reference/api/org/eclipse/swt/browser/Browser.html#setText-java.lang.String-">setText</a></em>
    method is used, or the file is registered as a <a href="#resources">static resource</a>.
    <br/>
  </p>

  <h3 id="resources">Resources</h3>
  <p>
    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 <i>no images</i>), or your non-HTML resources can be loaded from
    a different HTTP-server, it will suffice to use the
    <em><a href="../reference/api/org/eclipse/swt/browser/Browser.html#setText-java.lang.String-">setText</a></em>
    method of the browser
    widget. This code would then also run in an SWT application. However, when using
    <em>setText</em>, 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
    <em>Browser</em>-based <a href="https://github.com/eclipsesource/rap-gmap">
    Google Maps widget</a>. 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
    <a href="resources.html">static resources</a>.
  </p>

  <h3>Limitations in JEE Mode</h3>
  <p>
      When using the
      <a href="application-setup.html#compat">JEE compatibility</a>
      <a href="../reference/api/org/eclipse/rap/rwt/application/Application.OperationMode.html">OperationMode</a>
      (the default for non-workbench based applications), then
      the <em>executeScript</em> and <em>evaluate</em> methods will not block program
      execution.
      Like with dialogs, a RAP-only method
      <em><a href="../reference/api/org/eclipse/swt/browser/Browser.html#evaluate-java.lang.String-org.eclipse.rap.rwt.widgets.BrowserCallback-">evaluate(String, BrowserCallback)</a></em>,
      is available, which lets you register a callback to receive the results of the <em>evaluate</em>
      call. However, this pattern makes implementing a traditional "getter" impossible.
      In <a href="application-setup.html#compat">SWT compatibility</a> mode you can write:
    </p>
    <pre  class="lang-java">
public String getText() {
  // assuming the web app is already fully loaded and initialized:
  return ( String )browser.evaluate( "return myWidget.getData();" );
}</pre>
  <p>
    In JEE compatibility mode you would have to write
    something like this:
  </p>
   <pre class="lang-java">
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 );
    }
  } );
}</pre>
  <p>
    If you are writing a custom widget that is supposed to feature getter that need to obtain their
    value using <em>evaluate</em>, either use the SWT compatibility mode, or consider
    another type of <a href="custom-widget.html">custom widget</a>.
  </p>

</body>
</html>