Jump to: navigation, search

Difference between revisions of "RAP/WebClient"

< RAP
(Communication)
(Communication)
 
(10 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
The web client is the default client delivered by the RAP server if an application URL is entered into a web browser.
 
The web client is the default client delivered by the RAP server if an application URL is entered into a web browser.
  
As of RAP 1.5, the following browsers are supported:
+
As of RAP 2.0, the following browsers are supported:
  
*Internet Explorer 7+
+
*Internet Explorer 7+  
 
*Google Chrome 7+
 
*Google Chrome 7+
*Firefox 3.5+
+
*Firefox 4+
 
*Safari 4+
 
*Safari 4+
 
*Opera 10+
 
*Opera 10+
Line 19: Line 19:
 
The web client is represented on the server by the class <code>org.eclipse.rap.rwt.client.WebClient</code>. (Since RAP 2.0.) An instance can be obtained via <code>org.eclipse.rap.rwt.RWT#getClient()</code>. Besides the methods specified by the <code>org.eclipse.rap.rwt.client.Client</code> interface, it also provides a number of constants that may be used in the configuration map of an [http://eclipse.org/rap/developers-guide/devguide.php?topic=advanced/application-configuration.html application entrypoint].  
 
The web client is represented on the server by the class <code>org.eclipse.rap.rwt.client.WebClient</code>. (Since RAP 2.0.) An instance can be obtained via <code>org.eclipse.rap.rwt.RWT#getClient()</code>. Besides the methods specified by the <code>org.eclipse.rap.rwt.client.Client</code> interface, it also provides a number of constants that may be used in the configuration map of an [http://eclipse.org/rap/developers-guide/devguide.php?topic=advanced/application-configuration.html application entrypoint].  
  
The <code>WebClient#getService()</code> method can be used to obtain the follwing supported services:  
+
The <code>WebClient#getService()</code> method can be used to obtain the follwing services:  
  
 
*<code>org.eclipse.rap.rwt.client.service.JavaScriptExecuter</code>
 
*<code>org.eclipse.rap.rwt.client.service.JavaScriptExecuter</code>
*<code>org.eclipse.rap.rwt.client.service.BrowserHistory</code>
+
*<code>org.eclipse.rap.rwt.client.service.JavaScriptLoader</code>
 +
*<code>org.eclipse.rap.rwt.client.service.UrlLauncher</code>
 +
*<code>org.eclipse.rap.rwt.client.service.BrowserNavigation</code>
 +
*<code>org.eclipse.rap.rwt.client.service.ExitConfirmation</code>
 +
*<code>org.eclipse.rap.rwt.client.service.ClientInfo</code>
  
Diferent clients may support different services. If you target multiple clients, check for null before using a service.
+
Currently all services are available regardless of the browser used. (Future services may not be supported by all browser.) However, other clients (not to be confused with ''other browser'') may support different services. If you target multiple clients. It is therefore advised to check for null before using a service.
  
 
= Custom Widget Development =
 
= Custom Widget Development =
  
Information on devoloping custom widgets targeting multiple platforms can be found [[RAP/Custom_Widgets|here]].
+
Information on developing custom widgets targeting multiple platforms can be found [[RAP/Custom_Widgets|here]].
  
Information on devoloping custom widgets native to the web client can be found [[RAP/Custom_Widgets#RAP-native_Custom_Widget|here]].
+
Information on developing custom widgets native to the web client can be found [[RAP/Custom_Widgets#RAP-native_Custom_Widget|here]].
  
 
= Technical information  =
 
= Technical information  =
Line 36: Line 40:
 
== Overview  ==
 
== Overview  ==
  
Until RAP 1.3 the web client was based on the [http://qooxdoo.org/ qooxdoo] JavaScript framework. For RAP 1.4 qooxdoo 0.7.4 was forked, trimmed down, and largely re-written to better fit the specific needs of the RAP project. Therefore, '''the API reference for qooxdoo is no longer valid for the RAP web client. '''  
+
Until RAP 1.3 the web client was based on the [http://qooxdoo.org/ qooxdoo] JavaScript framework. For RAP 1.4 qooxdoo 0.7.4 was forked, trimmed down, and largely re-written to better fit the specific needs of the RAP project. Therefore, '''the API reference for qooxdoo is no longer valid for the RAP web client. ''' In RAP 2.0 the "qx" namespace on the client is gone, everything is now "rwt" for internal API, and in "rap" for public API.
  
 
RAP uses HTML to render most of its widgets. The &lt;div&gt; tag is nearly the only HTML ''element'' used. Exceptions are the &lt;input&gt; elements for text fields and the Upload widget, and &lt;iframe&gt; to support the Browser widget and BrowserHistory. (&lt;img&gt; may be used in some older code that is targeted to be removed.) CSS3 is used where available to render visual effects like rounded borders. If CSS3 is not sufficiently supported, SVG and VML are used as a fallback.
 
RAP uses HTML to render most of its widgets. The &lt;div&gt; tag is nearly the only HTML ''element'' used. Exceptions are the &lt;input&gt; elements for text fields and the Upload widget, and &lt;iframe&gt; to support the Browser widget and BrowserHistory. (&lt;img&gt; may be used in some older code that is targeted to be removed.) CSS3 is used where available to render visual effects like rounded borders. If CSS3 is not sufficiently supported, SVG and VML are used as a fallback.
Line 50: Line 54:
 
The main task of the client-server communication is to synchronize client and server objects, typically widgets. Basically, each synchronizeable object in a RAP session has three simultaneous representations:  
 
The main task of the client-server communication is to synchronize client and server objects, typically widgets. Basically, each synchronizeable object in a RAP session has three simultaneous representations:  
 
*The server-side (java) object, which is used by the application developer.
 
*The server-side (java) object, which is used by the application developer.
*The 'virtual' protocol object, which is what is referenced in the server-client dialogue, but not actually stored anywhere.
 
 
*The client-side object, which (in case of widgets) renders the graphics and handles user events.
 
*The client-side object, which (in case of widgets) renders the graphics and handles user events.
 +
*A 'virtual' protocol object, which is what is referenced in the server-client dialogue. The are also referred to as "Remote Objects".
  
The translation between server object is virtual object is managed by LifeCycle adapters, while the translation between virtual object and client object is managed by protcol adapters. Future RAP versions might align the two types of adapters.  
+
The translation between server object the protocol is managed by LifeCycle adapters (for core widgets) or by the RemoteObject API, while the translation between protocl and client object is managed by protcol "type handlers".  
  
With this archtecture, both client and server can be replaced, only the API for the virtual object is constant. The 'virtual' objects API is also used in the [[RAP\ClientScripting|ClientScripting] add-on.
+
With this architecture, both client and server can be replaced, only the API for the remote object is constant. The 'virtual' remote objects API is also used in the [[RAP/ClientScripting|ClientScripting]] add-on.
 
+
== Internal API ==
+
 
+
''NOTE: This API is not yet stable and may change without further notice in minor releases. This wiki will aways reflect the current RAP version (milestones). API reference that is considered stable will be moved to the developers guide.
+
 
+
*<code>[[RAP/AdapterRegistry|rwt.protocol.AdapterRegistry]]</code>
+
*<code>[[RAP/ObjectRegistry|rwt.protocol.ObjectRegistry]]</code>
+
*<code>[[RAP/ServerObject|rwt.protocol.ServerObject]]</code>
+

Latest revision as of 05:13, 21 January 2013

General Information

The web client is the default client delivered by the RAP server if an application URL is entered into a web browser.

As of RAP 2.0, the following browsers are supported:

  • Internet Explorer 7+
  • Google Chrome 7+
  • Firefox 4+
  • Safari 4+
  • Opera 10+
  • iOs 5+ (Safari)
  • Android 3+ (stock browser, limited)

The browser must have javascript enabled and be allowed to dispatch XMLHttpRequests. No other plug-ins (like flash) are required. RAP 1.4 was the last version to support Internet Explorer 6. Some advanced visual effects like shadows may not work on all of the older browsers. The best performance can be achieved with Chrome and Safari, while Internet Explorer 7 and the Android stock browser are the slowest.

Server API

The web client is represented on the server by the class org.eclipse.rap.rwt.client.WebClient. (Since RAP 2.0.) An instance can be obtained via org.eclipse.rap.rwt.RWT#getClient(). Besides the methods specified by the org.eclipse.rap.rwt.client.Client interface, it also provides a number of constants that may be used in the configuration map of an application entrypoint.

The WebClient#getService() method can be used to obtain the follwing services:

  • org.eclipse.rap.rwt.client.service.JavaScriptExecuter
  • org.eclipse.rap.rwt.client.service.JavaScriptLoader
  • org.eclipse.rap.rwt.client.service.UrlLauncher
  • org.eclipse.rap.rwt.client.service.BrowserNavigation
  • org.eclipse.rap.rwt.client.service.ExitConfirmation
  • org.eclipse.rap.rwt.client.service.ClientInfo

Currently all services are available regardless of the browser used. (Future services may not be supported by all browser.) However, other clients (not to be confused with other browser) may support different services. If you target multiple clients. It is therefore advised to check for null before using a service.

Custom Widget Development

Information on developing custom widgets targeting multiple platforms can be found here.

Information on developing custom widgets native to the web client can be found here.

Technical information

Overview

Until RAP 1.3 the web client was based on the qooxdoo JavaScript framework. For RAP 1.4 qooxdoo 0.7.4 was forked, trimmed down, and largely re-written to better fit the specific needs of the RAP project. Therefore, the API reference for qooxdoo is no longer valid for the RAP web client. In RAP 2.0 the "qx" namespace on the client is gone, everything is now "rwt" for internal API, and in "rap" for public API.

RAP uses HTML to render most of its widgets. The <div> tag is nearly the only HTML element used. Exceptions are the <input> elements for text fields and the Upload widget, and <iframe> to support the Browser widget and BrowserHistory. (<img> may be used in some older code that is targeted to be removed.) CSS3 is used where available to render visual effects like rounded borders. If CSS3 is not sufficiently supported, SVG and VML are used as a fallback.

Drawing (via Canvas/GC) is implemented using the HTML5 <canvas> element, except in Internet Explorer 7 and 8, where VML is used instead. <canvas> is significantly faster than VML, and complex drawings should be avoided when targeting IE7/8.

Communication

The web client uses the RAP Protocol to communicate with the RAP server via HTTP-requests. The protocol was introduced in RAP 1.5 for server-to-client messages, and is also used for client-to-server messages since RAP 2.0.

The syntax of the protocol is stable API since RAP 2.0, while the actual types and properties are currently not considered public API. (Meaning there may be breaking changes in minor releases). All changes are documented in the corresponding bugzilla entries using the keyword "protocol" on the whiteboard field.

The main task of the client-server communication is to synchronize client and server objects, typically widgets. Basically, each synchronizeable object in a RAP session has three simultaneous representations:

  • The server-side (java) object, which is used by the application developer.
  • The client-side object, which (in case of widgets) renders the graphics and handles user events.
  • A 'virtual' protocol object, which is what is referenced in the server-client dialogue. The are also referred to as "Remote Objects".

The translation between server object the protocol is managed by LifeCycle adapters (for core widgets) or by the RemoteObject API, while the translation between protocl and client object is managed by protcol "type handlers".

With this architecture, both client and server can be replaced, only the API for the remote object is constant. The 'virtual' remote objects API is also used in the ClientScripting add-on.