View source for RAP/Incubator/ClientScripting

'''Note''': Since RAP 2.2M1 ClientScripting is included into the RAP core (org.eclipse.rap.rwt bundle). The ClientScripting incubator projects are no longer compatible with RAP 2.2M1+ and must be used '''only''' with older RAP versions.

== Overview  ==

Conventional RAP applications are running almost entirely on a Server, with a thin client only rendering a user interface with some limited interactivity. This has several advantages, but it also means all application-relevant events have to be forwarded to the Server before being processed, causing small delays and traffic. Scenarios where interactions occur with a high frequency, like typing or mouse movements, would therefore be undesirable. 

This is where RAP ClientScripting can help. ClientScripting allows developers to handle some of the events directly on the client, without creating any http-requests. This is ideal to customize or enhance the behavior of specific widgets, making it much less often necessary to develop RAP custom-widgets. 

The scripts themselves are written in JavaScript on a SWT-like API. This allows application developers with SWT-experience to get started right away, and makes porting between SWT and RAP-ClientScripting fairly easy. Even without any JavaScript-experience, this document should provide you with all the basics you need for ClientScripting. 

The ClientScripting feature is currently in early development, aiming to enable only some specific use cases. However, all API published here should be stable and is unlikely to change in the future. The project is <strike>currently hosted on </strike>[https://github.com/eclipsesource/rap-clientscripting <strike>GitHub</strike>] available in the [http://git.eclipse.org/c/rap/incubator/org.eclipse.rap.incubator.clientscripting.git/ RAP incubator]. <strike>The projects "master" branch is always compatible with the current RAP [http://git.eclipse.org/c/rap/org.eclipse.rap.git/ "master" branch]/ [http://eclipse.org/rap/downloads/ nightly build].</strike> For RAP releases and milstones, check out [http://git.eclipse.org/c/rap/incubator/org.eclipse.rap.incubator.clientscripting.git/refs/ the commit with the tag/branch best matching to the version you are using] (procided since RAP 2.0M4). We also have a Nightly builds p2 repository (http://download.eclipse.org/rt/rap/incubator/nightly/clientscripting/) and a RAP 2.0 compatible p2 repository (http://download.eclipse.org/rt/rap/incubator/2.0/clientscripting/)

Questions, suggestions and [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=specific;order=relevance%20desc;bug_status=__open__;product=RAP;content=ClientScripting;list_id=995525 bug reports] are welcome!

== Java API  ==

Client event processing works like untyped event handling in SWT, with the main difference that the handler itself has to be written in JavaScript, and is added to the widget using a method on the listener itself. It also does (naturally) not have access to all of the resources and functionality that would be available on the server.

=== The ClientListener Class  ===

Instances of this class represent a JavaScript function that can be attached to any widget for any supported event. It's similar in concept to <code>org.eclipse.swt.widgets.Listener</code>, but can only be executed on the client.

{| align="left" width="100%" height="73" cellspacing="0" cellpadding="3" border="1" style="margin: auto auto 1em auto;"
|-
! align="left" colspan = "2" bgcolor="#CCCCFF" style = "font-family:serif;font-size:16pt" | <b>Constructor Summary</b>
|- valign="top"
| colspan = "2" align="left"| <code><b>ClientListener( String scriptCode )</b></code><br> Creates an instance of <code>ClientListener</code> using the given String as JavaScript source code.
|}

Example:
<pre>
widget.addListener( SWT.Verify, new ClientListener( javascript) );
</pre>

The JavaScript source code can define any number of named function, either with "<code>var myFunction = function(){};</code> or "<code>function myFunction(){};</code>". One of the functions has to be named "handleEvent" and take one argument (the event). Example: "<code>var handleEvent = function( event ){ ... };</code>". The other functions can be called from <code>handleEvent</code> to be used as helper functions. The order in which the functions are defined is not relevant.

If your script is longer than a few lines, we recommend to read it from an external file. The clientscripting demo provides a [http://git.eclipse.org/c/rap/incubator/org.eclipse.rap.incubator.clientscripting.git/tree/bundles/org.eclipse.rap.clientscripting.demo/src/org/eclipse/rap/clientscripting/demo/ResourceLoaderUtil.java util class] to help with that.

For the documentation of the "event" object, see the JavaScript chapter below. Note that the function is executed without any context ("this"), meaning that unlike the SWT <code>handleEvent</code> method, it is not a member of an object.

=== Supported Event Types  ===

{| align="left" width="100%" height="73" cellspacing="0" cellpadding="3" border="1" style="margin: auto auto 1em auto;"
|-
! <b>Event Type</b>
! <b>Notes</b>
|- valign="top"
| align="right"| <code>KeyDown</code>
| Fired once when pressing a key, then repeatedly while holding it down. The <code>doit</code> flag can be used to prevent the character from beeing inserted.
|- valign="top"
| align="right"| <code>KeyUp</code>
| Fired when releasing a key.
|- valign="top"
| align="right"| <code>MouseDown</code>
| Fired when pressing a mouse button.
|- valign="top"
| align="right"| <code>MouseUp</code>
| Fired when releasing a mouse button.
|- valign="top"
| align="right"| <code>MouseMove</code>
| Fired when moving the mouse within the widget. This type is not supported in server-side RAP, only clientscripting. 
|- valign="top"
| align="right"| <code>MouseEnter</code>
| Fired when moving the mouse over the widget. This type is not supported in server-side RAP, only clientscripting.
|- valign="top"
| align="right"| <code>MouseExit</code>
| Fired when moving the mouse out of the widget. This type is not supported in server-side RAP, only clientscripting.
|- valign="top"
| align="right"| <code>MouseDoubleClick</code>
| Fired when clicking twice.
|- valign="top"
| align="right"| <code>FocusIn</code>
| Fired when widget is focused.
|- valign="top"
| align="right"| <code>FocusOut</code>
| Fired when widget is blured.
|- valign="top"
| align="right"| <code>Paint</code>
| Fired when widget appears, is changing size, or when "redraw" is called on the widget either in java, or in clientscripting. Only supported on <code>Canvas</code>.
|- valign="top"
| align="right"| <code>Selection</code>
| Fired on List widgets when selection changes. Other widgets are currently not supported.
|- valign="top"
| align="right"| <code>DefaultSelection</code>
| Fired on List widgets when an item is double-clicked. (As in SWT and server-side RAP.) Other widgets are currently not supported.
|- valign="top"
| align="right"| <code>Modify</code>
| Fired then the value of the "text" property of a <code>Text</code> widget changes. Not supported on other widgets.
|- valign="top"
| align="right"| <code>Verify</code>
| Fired then the value of the "text" property of a <code>Text</code> widget is changed by the user. Not supported on other widgets. The <code>doit</code> flag can be used to prevent the change. The "text" field of the event may be changed to replace the inserted text.
|}

== JavaScript API  ==

=== The Event Object  ===

This object is given as the first argument when calling a client event listener function. Its API is designed after <code>org.eclipse.swt.widgets.Event</code>. 

{| align="left" width="100%" height="73" cellspacing="0" cellpadding="3" border="1" style="margin: auto auto 1em auto;"
|-
! colspan = "2" bgcolor="#CCCCFF" style = "font-family:serif;font-size:16pt" | <b>Field Summary</b>
|- valign="top"
| align="right"| <code>number</code>
| <code><b>type</b></code><br> the type of event, as defined by the event type constants in object <code>SWT</code>
|- valign="top"
| align="right"| <code>Widget</code>
| <code><b>widget</b></code><br> an object representing the widget that issued the event. 
|- valign="top"
| align="right"| <code>boolean</code>
| <code><b>doit</b></code><br> depending on the event, a flag indicating whether the operation should be allowed. Setting this field to false will cancel the operation. Currently supported only for key and mouse events on <code>Text</code> and <code>Text</code>-like widgets.
|- valign="top"
| align="right"| <code>number</code>
| <code><b>keyCode</b></code><br> depending on the event, the key code of the key that was typed, as defined by the key code constants in object <code>SWT</code>. When the character field of the event is ambiguous, this field contains the unaffected value of the original character. For example, typing Shift+M or M results in different characters ( 'M' and 'm' ), but the same keyCode (109, character code for 'm').
|- valign="top"
| align="right"| <code>string</code>
| <code><b>character</b></code><br> depending on the event, the character represented by the key that was typed. This is the final character that results after all modifiers have been applied. For non-printable keys (like arrow-keys) this field is not set. Changing its value has no effect.
|- valign="top"
| align="right"| <code>number</code>
| <code><b>stateMask</b></code><br> depending on the event, the state of the keyboard modifier keys and mouse masks at the time the event was generated.
|- valign="top"
| align="right"| <code> number </code>
| <code><b>button</b></code><br> the button that was pressed or released; 1 for the first button, 2 for the second button, and 3 for the third button, etc.
|- valign="top"
| align="right"| <code> number </code>
| <code><b>x</b></code><br> x coordinate of the pointer at the time of the event
|- valign="top"
| align="right"| <code> number </code>
| <code><b>y</b></code><br> y coordinate of the pointer at the time of the event
|- valign="top"
| align="right"| <code> string </code>
| <code><b>text</b></code><br> depending on the event, the new text that will be inserted. Setting this field will change the text that is about to be inserted or deleted.
|- valign="top"
| align="right"| <code> number </code>
| <code><b>start</b></code><br> depending on the event, the range of text being modified. Setting these fields has no effect.
|- valign="top"
| align="right"| <code> number </code>
| <code><b>end</b></code><br> depending on the event, the range of text being modified. Setting these fields has no effect.
|- valign="top"
| align="right"| <code> object </code>
| <code><b>gc</b></code><br> the graphics context to use when painting
|}

The fields "keyCode" and "character" are set on key and verify events. "stateMask" is set for key and mouse events. "x", "y" and "button" are set for mouse events. "text", "start" and "end" are set for verify events. "gc" is set only on paint events. The "doit" flag is supported on key and verify events.

==== GC ====
The client-side GC does not feature the API of the SWT GC. Instead it supports a subset of the HTML5 Canvas API (http://www.w3.org/TR/2dcontext/):
* Fields:
** strokeStyle
** fillStyle
** lineWidth
** lineJoin
** lineCap
** miterLimit
** globalAlpha
* Methods:
** save
** restore
** beginPath
** closePath
** clearRect (Limitation: in IE 7+8 arguments are ignored, the entire canvas is cleared)
** stroke
** fill
** moveTo
** lineTo
** quadraticCurveTo
** bezierCurveTo
** rect
** arc (Limitation: in IE 7+8 not available in RAP 1.5, only RAP 2.x)
** drawImage
** createLinearGradient (Limitations: In IE 7+8, the gradient can be only be drawn either vertically or horizontally. Calls to "addColorStop" must be in the order of the offsets and can not overwrite previous colorsStops)

* In IE7+8, these are all supported methods. More may be supported on other browser, since the the native HTML5 canvas is used.

* HTML5 canvas does not support drawing ellipses. A possible workaround can be found [http://stackoverflow.com/a/2173084/1466158 here].

It is not a good idea to attach a server-side AND a client-side paint listener. Both will be triggered.

=== The SWT Object ===

The SWT object contains a number of public contants. It is available as a local variable within the scope of any ClientScripting function. Its API is designed after <code>org.eclipse.swt.SWT</code>, but the values for the constants may be different. To get an overview of all available constants and their purpose, view the file "js/org/eclipse/rap/clientscripting/SWT.js" from the ClientScripting bundle.

=== The Widget Object ===
The Widget object in RAP ClientScripting is an abstract representation of an SWT widget. It has a subset of the API of the actual SWT Widget it represents. In some cases the API may slightly differ. 

==== Setter ====

All widgets have setter functions for all properties defined in the [http://wiki.eclipse.org/RAP/Protocol RAP-Protocol]. All setter take exactly one argument. For a case of overloaded setter in SWT, they are usually taking the most complex/complete type of argument. For example, <code>Text</code> has "<code>setSelection( int start )</code>", "<code>setSelection( Point selection )</code>" and "<code>setSelection( int start, int end )</code>". The setter "<code>setSelection( Point selection )</code>" is one with the complete data and takes only one argument. Since <code>Point</code> is represented in ClientScripting as an Array (see Data Types below), the setter is "<code>setSelection( [ start, end ] )</code>".

For now a list of all the properties is available in the README.md in the ClientScripting bundle. '''Please be aware that as of now, changing a widgets property with these setter will in most cases only affect it's client side representation.''' Only properties that can also be changed by a user's interaction with the UI (like selection) will also be updated on the java widget instance. This will be improved in later versions to fully synchronize all properties.

==== Getter ====

Currently only some getters are available. A list of all properties that have getters is available in the README.md in the ClientScripting bundle. Note that the getter might return null, but never undefined.

==== setData, getData and WidgetDataWhiteList ====

The Widget provides object a <code>setData</code> and a <code>getData</code> function. Similar to SWT, these allow to attach data to a widget instance without affecting the widget itself. Unlike SWT any value can be stored with setData, not just objects. By default, the data storage on the client is not synchronized with the data storage on the actual SWT Widget.

{| align="left" width="100%" height="73" cellspacing="0" cellpadding="3" border="1" style="margin: auto auto 1em auto;"
|-
! colspan = "2" bgcolor="#CCCCFF" style = "font-family:serif;font-size:16pt" | <b>Function Summary</b>
|- valign="top"
| align="right"| <code>undefined</code>
| <code><b>setData( string key, value value )</b></code><br> stores the given value. The key is mandatory.
|- valign="top"
| align="right"| <code>value</code>
| <code><b>getData( string key )</b></code><br> gets a stored value. The key is mandatory.
|}

Data attached to the SWT Widget can be transfarred to the ClientScripting widget. To do so, the key for that data has to be added to the WidgetDataWhiteList, like so:

<pre>
WidetDataWhiteList.addKey( "foo" );
widget.setData( "foo", "myData" );
</pre>

The key has only to be added once per session, but adding it multiple times has no side effects. The following types are supported:

{|cellspacing="0" cellpadding="1" border="1" style="font:12px courier new"
|-
|null 
|-
|String
|-
|Byte 
|-
|Short
|-
|Integer
|-
|Long 
|-
|Double 
|-
|Float 
|-
|Boolean 
|-
|int[] 
|-
|boolean[] 
|-
|String[]
|-
|Object[]
|-
|Map  
|-
|JsonValue 
|-
|}

Changing the value on the client does not change it on the server. 

<span id="crosswidget">Widgets can not be transferred, but the id can:</span>

Java:
<pre>
widget.setData( "otherWidget", WidgetUtil.getId( otherWidget ) );
</pre>
JavaScript:
<pre>
var otherWidget = rap.getObject( widget.getData( "otherWidget" ) );
</pre>

ClientScripting enhances the <code>[http://download.eclipse.org/rt/rap/doc/2.0/guide/reference/jsdoc/symbols/rap.html#.getObject rap#getObject]</code> method so that the returned wrapper is ClientScripting compatible. (It is the same representation as used in event.wigdet.)


==== Methods on Controls ====

Controls provide some additional methods:

{| align="left" width="100%" height="73" cellspacing="0" cellpadding="3" border="1" style="margin: auto auto 1em auto;"
|-
! colspan = "2" bgcolor="#CCCCFF" style = "font-family:serif;font-size:16pt" | <b>Function Summary</b>
|- valign="top"
| align="right"| <code>boolean</code>
| <code><b>forceFocus()</b></code><br> forces the control to get keyboard focus, even if it can not be focused by the user (by mouse mouse/keyboard). Returns <code>true</code> if the control got focus, and <code>false</code> if it was unable to.
|- valign="top"
| align="right"| <code>undefined</code>
| <code><b>redraw()</b></code><br> fires a <code>Paint</code> event. Only useful with <code>Canvas</code>.
|}

==== Data Types ====

The type and format of the values that can be set/get on the widget objects is a javascript-specific approximation of its SWT counterpart.
They are identical to those used in the RAP Protocol.

For simple data types/values the mapping is as follows:

{| cellspacing="0" cellpadding="3" border="1" style="margin: auto auto 1em 1em;"
! SWT
! ClientScripting
|-
| void || undefined
|-
| null || null
|-
| boolean || boolean
|-
| int || number, but treated like int
|-
| float || number
|-
| String || string
|-
| char || string with length of 1
|}

For complex types see http://wiki.eclipse.org/RAP/Protocol#Common_Data_Types.

== Known Limitations ==

This is a list of limitations on existing features with the current ClientScripting implementation. Limitations are not bugs, those are tracked in bugzilla only. If a bugzilla entry for a listed issue exists, it should be linked, but not all limitations are possible/planned to be fixed in the future.

* As mentioned above, there are only some '''getter''' available on the widget object. New ones will added as needed.
* Also mentioned above, many property changes (such as background color) are currently '''not synchronized''' with the server. 
* The 'streams/1.5' and 'streams/2.0' branches of ClientScripting work with RAP 1.5/2.0, the master is always in sync with the RAP master.
* The '''doit''' flag is currently only supported on the Text Widget for Key and Verify events.
* It is not (and will not be) possible to prevent Text Widget selection/carret change by mouse (using doit flag). Its also not supported to set the Text selection property in a '''MouseDown''' event. These are also not working (correctly) in SWT. Changing selection on Text on a MouseUp works.
* '''Verify''' event: 
** Currently only supported on Text. 
** Setting the text or selection property <i>of the target</i> within the Verify event is not supported, but it doesn't produce useful results in SWT either. The modiy event is better suited for this.
** Changing the events "text" field has no effect if its empty to begin with. (I.e. deleting can not be used to insert text).
* In SWT, some '''key constants''' can be compared with both the keyCode field and the character field (<code>SWT.DEL, SWT.ESC, SWT.BS, SWT.BS, SWT.CR, SWT.TAB</code>). In ClientScripting they can only be compared with the keyCode field. The character field will either not be set for these keys, or contain a (javascript) string, while these constants are numbers.

Get a list of open bugs and enhancement requests in [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=specific;order=relevance%20desc;bug_status=__open__;product=RAP;content=ClientScripting our bugzilla]. Report bugs or enhancement requests on bugzilla with a "[ClientScripting]" prefix on the summary.

== General Restrictions and Discouraged Usage ==

For the RAP default client, ClientScripting runs in the same environment as the client itself. 
For reasons of stability, compatibility and security you should not:

* Try to access any internal RAP client API.
* Manipulate any of the ClientScripting objects in an undocumented manner.
* Access any DOM (HTML) elements.
* Manipulate any of JavaScript's own prototypes/constructors (Object, Function, etc.).
* Set a widget's property to any invalid/unsupported values. 

Violating any of the above guidelines might create unpredictable results, even if the application seems to run fine at first.

Accessing the window/document Objects is discouraged for cross-browser/cross-client compaibility concerns. You can do so at your own risk.

Creating global variables is also heavily discouraged, and can easily happen by accident if a variable is created without the "var" keyword.

For security reasons you should be aware that, unlike RAP sourcecode written in Java, all ClientScripting functions (JavaScript sourcecode) are currently transferred to the client completely unaltered (including comments), and can be read by any user with enough technical expertice.

== JavaScript Hints for Java Developer ==

Developers experienced with Java programming and less familiar with (or completely new to) JavaScript might find the following hints useful in regard to ClientScripting:

=== Noteable differences between Java and JavaScript ===

* <b>JavaScript variables are dynamically typed and have function scope</b>
All local variables in JavaScript are delcared with "var" and can contain any type (undefined, null, number, boolean, string, object). It is not relevant at all where in the function it is declared, its scope is always the entire function.

* <b>Strings are not objects</b>
Strings are primitives in JavaScript, and are compared with "<code>==</code>" (or "<code>===</code>"), not "<code>.equals</code>". However, string primitives can be coerced into a string object, on which several useful methods are [http://www.w3schools.com/jsref/jsref_obj_string.asp available].

* <b>A number is not always a number</b>
When calculating a numeric value in JavaScript, the result might not always be a number, even if it is of the <i>type</i> number. The two cases are <code>infinity</code> (e.g. "<code>10/0 == infinity</code>") and <code>NaN</code> (not a number, e.g. "<code>Math.sqrt( -1 )</code>"). <code>NaN</code> can be detected only by using <code>isNaN</code> (e.g. "<code>isNaN( Math.sqrt( -1 ) ) == true</code>"). If a number is neither <code>NaN</code> nor <code>infinity</code>, it can do most things Javas <code>int</code> or <code>double</code> can, including bitwise operations.

* <b>Arrays have dynamic length</b>

Even though their syntax is very similar, JavaScript Arrays behave more like Java Lists than Java Arrays. They can store different types in different slots, and can change their length as needed. They also have differently named, but similarly working [http://www.w3schools.com/jsref/jsref_obj_array.asp methods].

=== Noteable similarities between Java and JavaScript ===

* <b>Objects and Maps</b>
JavaScript Objects (created with a literal "<code>{}</code>") can be used like Java Maps. A "<code>map.put( "key", value )</code>" would be "<code>map[ key ] = value</code>", and a "<code> map.get( "key" )</code>" would be "<code>map[ "key" ] </code>". In JavaScript, <code>value</code> could be of any type.

* <b>System.out.println and console.log</b>
Most browser (but not all!) have some form of javascript console. They all have at least one function in common that can be used like <code>System.out.println</code>, which is <code>console.log</code>. Some browser also have <code>console.trace</code>. Browser not supporting <code>console.log</code> (or in case of InternetExplorer, not having it activated), will crash when calling that method, so remember removing all occurrences of console from your JavaScript code after debugging.

* <b>Math and Math</b>
The Java <code>Math</code> class and the JavaScript <code>Math</code> object have almost identical [http://www.w3schools.com/jsref/jsref_obj_math.asp API]. 

* <b>Date and Date</b>
The JavaScript constructor <code>[http://www.w3schools.com/jsref/jsref_obj_date.asp Date]</code> creates objects almost identical in API to instances of Javas <code>Date</code> class.

* <b>Regular Expressions and RegExp</b>
JavaScript also supports [http://www.w3schools.com/jsref/jsref_obj_regexp.asp regular expressions].

* <b>char and string</b>
JavaScript has no <code>char</code> type. For ClientScripting, a string with a length of one character is used instead. This allows for comparison like "<code>event.character == "A"</code>", but not "<code>event.character >= 65</code>". To do that use <code>charCodeAt</code>. Example: "<code>event.character.charCodeAt( 0 ) >= 65</code>".