RAP 2.2M1 published, ClientScripting changes

The first milestone of RAP 2.2 has been published last Friday. It’s main attraction is the RWT Scripting feature which was formerly known as the incubator “ClientScripting” project. If you are currently using ClientScripting and wish to upgrade to RAP 2.2 (which will be released in December 2013), you should be aware of some breaking changes*:

• Namespace: The ClientListener has been moved from org.eclipse.rap.clientscripting to org.eclipse.rap.rwt.scripting.

• Removed deprecated API: The methods addTo, removeFrom and dispose are no longer present. Use only widget.addListener( type, clientListener) and widget.removeListener( type, clientListener ).

• Moved event type constants: Previously the ClientListener held the event type constants supported by ClientScripting, including some that were not supported by RAP and therefore not present in the SWT class (e.g. MouseEnter, MouseExit, …). These have been removed and the missing constants have been added to the SWT class. This does not mean that these events are now supported by widgets in general, they still only work with ClientListener.

• Supported widgets: The number of widgets that support ClientListener has been reduced to (currently) Canvas, Composite, Text, Button and Label. There are technical reasons for this, but we also want (from now on) to only support Scripting for widgets when there are actual use cases. We will likely add some more widgets to this list until the 2.2 release. See also WebClient API integration below.

• Supported properties: Previously most properties of a widget could be set by ClientScripting, but the setter were mostly undocumented, and in most cases the changes made by Scripting were applied only on the client and not to the actual java widget. Now the WebClient API reference will list all officially supported methods, and changes made by these will be synchronized back to the server (unless documented otherwise). Most previously existing methods are still present, but they are not API and may or may not work as expected. Currently only foreground and background properties are supported on all widgets, but the 2.2 release will at least also support enabled, visible, toolTipText, cursor, and some widget-specific properties.

• DataKeys: The recently introduced method WidgetDataWhiteList.addKey( String key ) is now part of the WidgetUtil class as registerDataKeys( String... keys ).

• WebClient API integration: The client method rap.getObject( id ) can now be used in Scripting to get a JavaScript instance of any scriptable widget. (Previously only the widget that fired the current event could be accessed, using event.widget.) This “cross-widget” scripting feature was a recent addition to ClientScripting, and is listed here as a reminder. Widgets that do not support ClientListener (as noted above) can also be accessed using rap.getObject( id ), but their API is not documented or officially supported.

The developers guide has been updated with an article on RWT Scripting. The ClientScripting wiki will link to this and other resources regarding migrating from ClientScripting to RWT Scripting.

Please note: The incubator version of ClientScripting is no longer compatible with RAP 2.2. If you migrate a project using ClientScripting to 2.2, you have to use the new API. The incubator project will not be affected by these changes and can still be used with RAP 1.5, 2.0 and 2.1.