bundles/org.eclipse.rap.doc/guide/articles/web-embedding.html - rap/org.eclipse.rap.tools - Git at Google

 <?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>
	<?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>