Add help article on the Client interface and client services.
diff --git a/bundles/org.eclipse.rap.help/help/html/advanced/branding.html b/bundles/org.eclipse.rap.help/help/html/advanced/branding.html
index 334d130..f127b43 100644
--- a/bundles/org.eclipse.rap.help/help/html/advanced/branding.html
+++ b/bundles/org.eclipse.rap.help/help/html/advanced/branding.html
@@ -12,7 +12,7 @@
<h1>Branding</h1>
<em>
- Note: Branding is only available when your RAP Application is used in a
+ Note: Branding is only available when your RAP Application is used in a
<a href = "application-setup.html#summary">setup</a> with workbench.
When using a <q>RAP with OSGi</q> or<q>RWT Standalone</q>
setup, see <q><a href = "application-configuration.html">Application Configuration</a></q>.
@@ -101,21 +101,6 @@
for the Display background property.
</p>
- <h4>exitConfirmationClass</h4>
- <p>
- An optional class that implements the interface <code>IExitConfirmation</code>.
- Implementations of this interface can control the exit confirmation that is shown whenever
- the user tries to close the browser window or tab or navigates to another URL.
- </p>
-
- <img src="../../images/branding/exitConfirmation.png" alt="Exit confirmation dialog"/>
-
- <p>
- <strong>NOTE:</strong>
- Note that this is feature is not supported by every browser. Furthermore,
- some browsers may show additional text in the confirmation dialog.
- </p>
-
<h4>Element additionalHeaders</h4>
<p>
An optional sub-element of a branding extension, that allows to add
diff --git a/bundles/org.eclipse.rap.help/help/html/rwt/client.html b/bundles/org.eclipse.rap.help/help/html/rwt/client.html
new file mode 100644
index 0000000..5ed435d
--- /dev/null
+++ b/bundles/org.eclipse.rap.help/help/html/rwt/client.html
@@ -0,0 +1,107 @@
+<?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) 2012 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>The RAP Client</title>
+ <link rel="stylesheet" href="../../../../PRODUCT_PLUGIN/book.css" type="text/css"/>
+</head>
+<body>
+
+ <h1>The RAP Client</h1>
+ <!-- TODO : add links to API reference -->
+ <p>
+ The term "RAP client" is used to identify the software that interacts with a RAP Server and
+ displays the actual UI of a RAP application. It does not include the enviroment an instance of
+ the client runs in (browser and/or OS), or the hardware ("device") itself.
+ </p>
+ <p>
+ The RAP project includes the default RAP client, written in JavaScript. It it will be referred
+ to simply as the "web client" from here on. The web client is downloaded and started
+ automatically when the URL of a RAP application is entered into a browser. In-depth
+ information about this client can be found in the
+ <a href="http://wiki.eclipse.org/RAP/WebClient">RAP Wiki</a>.
+ Other client
+ implementations than the web client are currently not part of the RAP project.
+ </p>
+ <h2>The Client Interface</h2>
+ <p>
+ Every client implementation is represented by a class implementing the <code>Client</code>
+ interface, e.g. <code>WebClient</code>. An instance of such a class can be obtained
+ from <code>RWT.getClient()</code>. It represents the client instance connected to the current
+ RAP session. By using the <code>instanceof</code> operator, the instance can be used to
+ identify the client.
+ </p>
+<pre><code> if( RWT.getClient() instanceof WebClient ) {
+ ...
+ }</code></pre><p>
+ The client interface mainly specifies methods to obtain information about the
+ client<!-- (e.g. the timezone) -->, while the client class itself only adds constants to be used in the
+ <a href = "../advanced/application-configuration.html">application configuration</a>.
+ In addition, the interface specifies the <code>getService()</code> method, described below.
+ </p>
+ <h2>Client Services</h2>
+ <p>
+ Client services are interfaces that can provide client-specific features.
+ The <code>getService</code> method of the client object can be used to obtain an implementation
+ of a given service, provided it is supported by the connected client. Wether or not
+ a service is supported depends on the RAP client implementation, but may also change
+ depending on the clients runtime enviroment and configuration. A list of supported services
+ can be found on the client class, e.g. <code>WebClient</code>.
+ </p>
+ <p>If a service is not supported, the method returns null. If this is a possibility given the
+ used service and targeted RAP client, a null check should be performed before using the service.
+ </p><p>
+ Example usage of a service:
+ </p>
+<pre><code> BrowserHistory history = RWT.getClient().getService( BrowserHistory.class );
+ if( history != null ) {
+ ...
+ }
+</code></pre>
+ <h3>
+ Services that are included in RWT
+ </h3>
+ <p>The services are all supported by the web client and can be found in the package
+ <code>org.eclipse.rap.rwt.client.service</code>.</p>
+ <ul>
+
+ <li style="margin-bottom:20px">
+ <b>BrowserHistory</b>
+ <br/>
+ Allows navigating within an application using the browser's <em>back</em> and
+ <em>forward</em> buttons. <br/>
+ <strong>NOTE:</strong> There are known issues when using the browser history
+ and the <code>Browser</code> widget in the same application.
+ </li>
+
+ <li style="margin-bottom:20px">
+ <b>ExitConfirmation</b>
+ <br/>
+ This service can control the exit confirmation that is shown whenever
+ the user tries to close the browser window or tab or navigates to another URL.
+ <img style="padding-top:5px" src="../../images/branding/exitConfirmation.png" alt="Exit confirmation dialog"/>
+ <br/>
+ <strong>NOTE:</strong>
+ Some browsers may show additional text in the confirmation dialog, or replace
+ the text completely for security reasons.
+ </li>
+
+ <li style="margin-bottom:20px">
+ <b>JavaScriptExecuter</b>
+ <br/>
+ Allows executing arbitrary JavaScript code in the window the RAP client runs in.
+ This is usually not necessary, but may be useful to work around minor limitations in RAP or
+ implement very simple features.
+ <br/>
+ <strong>NOTE:</strong>
+ This feature allows manipulating to the html DOM or accessing internals of the web client.
+ Doing so is <b>not</b> recommended and may have unintended consequences, including
+ crashing the client.
+ </li>
+
+ </ul>
+</body>
+</html>
diff --git a/bundles/org.eclipse.rap.help/help/html/rwt/differences.html b/bundles/org.eclipse.rap.help/help/html/rwt/differences.html
index c1ea7be..ee68c6e 100644
--- a/bundles/org.eclipse.rap.help/help/html/rwt/differences.html
+++ b/bundles/org.eclipse.rap.help/help/html/rwt/differences.html
@@ -21,17 +21,45 @@
</p>
<p>
RWT also provides some additional features that are not part of SWT.
- Partly, these are features related to web clients such as the browser history,
- partly enhancements of SWT widgets such as the HTML markup support in widgets.
+ Partly, these are features related to the RAP client such as the browser history,
+ partly enhancements of SWT widgets such as the HTML markup support.
However, RWT does not add any new API to the classes adopted from SWT.
All RWT features are accessible by API in the package <code>org.eclipse.rap.rwt</code>.
- Many of the additional features are activated using the widget's <code>setData</code>
- method with a constant from the <code> RWT</code> class as the key, for example
- <code>table.setData( RWT.MARKUP_ENABLED, Boolean.TRUE )</code>.
+ Most of the widget-specific additional features are activated using the
+ widget's <code>setData</code> method with a constant from the <code> RWT</code> class as the
+ key. For example <code>table.setData( RWT.MARKUP_ENABLED, Boolean.TRUE )</code>.
+ Others additional features may be accessed via the <code>Client</code> interface.
</p>
<h2>Notable Additional Features</h2>
<ul>
+
+ <li id = "client" style="margin-bottom:20px">
+ <b>Client Information and Client Services:</b> <code>Client</code>, <code>ClientService</code>
+ <br/>
+ Any interaction with the RAP client that is not directly related to a specific widget or to
+ <code>Display</code> is handled by the <code>Client</code> class. That includes:
+ <ul>
+ <li>Interacting with the browsers history.</li>
+ <li>Executing JavaScript.</li>
+ <li>Configuring the exit confirmation message.</li>
+ <!-- <li>Dicovering the users locale and timezone.</li> -->
+ <!-- <li>Updating the UI from a background thread.</li> -->
+ <!-- <li>Opening an new browser window.</li> -->
+ </ul>
+ The <code>Client</code> interface and client Services are documented in more detail
+ <a href="client.html">here</a>.
+ </li>
+
+ <!-- TODO move after this becomes a client service -->
+ <li style="margin-bottom:20px">
+ <b>External Browser Windows:</b> <code>ExternalBrowser</code>
+ <br/>
+ This widget allows opening (and closing) a new browser window or tab to display content from
+ a given URL.
+ Note that depending on the browser configuration, this may be prevented by a popup-blocker.
+ </li>
+
<li style="margin-bottom:20px">
<b>HTTP File Upload:</b> <code>FileUpload</code>
<br/>
@@ -48,20 +76,6 @@
</li>
<li style="margin-bottom:20px">
- <b>External Browser Windows:</b> <code>ExternalBrowser</code>
- <br/>
- This widget allows opening (and closing) a new browser window or tab to display content from
- a given URL.
- Note that depending on the browser configuration, this may be prevented by a popup-blocker.
- <!--
- The user's RAP session is not affected by this additional window.
- Unlike the <code>Browser</code> widget, the content of an external browser window can not
- communicate with the RAP application.
- ???
- -->
- </li>
-
- <li style="margin-bottom:20px">
<b>Markup in Widgets:</b> <code>Label</code>, <code>CLabel</code>, <code>List</code>,
<code>Tree</code> and <code>Table</code>
<br/>
@@ -97,17 +111,7 @@
</li>
<li style="margin-bottom:20px">
- <b>Browser History Support:</b>
- <code>IBrowserHistory</code>
- <br/>
- RWT supports navigating within an application using the browser's <em>back</em> and
- <em>forward</em> buttons.
- Use <code>RWT.getBrowserHistory()</code> to access it.
- Note that there are known issues when using the browser history and the <code>Browser</code>
- widget in the same application.
- </li>
-
- <li style="margin-bottom:20px">
+ <!-- TODO rename interfaces -->
<b>Multi-User Environment:</b> <code>ISettingsStore</code>, <code>IApplicationStore</code>,
<code>ISessionStore</code>, <code>IServiceStore</code>, <code>SessionSingletonBase</code>
<br/>
@@ -115,6 +119,7 @@
is that RWT operates in a multi-user environment.
This topic has its own <a href="scopes.html">article</a>.
</li>
+
</ul>
<h2>Notable Limitations</h2>
@@ -146,7 +151,7 @@
<code>setClipping</code>, <code>setTransform</code>, <code>setInterpolation</code>
<code>setLineDash</code> and <code>setXORMode</code>.
Performance and results of a drawing operations can differ depending on the browser.
- <!--
+ <!--
See also Self-Drawing custom widget.
???
-->
diff --git a/bundles/org.eclipse.rap.help/help/toc.xml b/bundles/org.eclipse.rap.help/help/toc.xml
index be26abe..e0ddf27 100644
--- a/bundles/org.eclipse.rap.help/help/toc.xml
+++ b/bundles/org.eclipse.rap.help/help/toc.xml
@@ -28,6 +28,8 @@
label="Differences between RWT and SWT"
href="help/html/rwt/differences.html">
</topic>
+ <topic href="help/html/rwt/client.html" label="The RAP Client">
+ </topic>
<topic
label="Scopes and Data Stores in RWT"
href="help/html/rwt/scopes.html">
