Bug 324434

Comment 1 Tim Buschtoens 2012-11-06 12:29:16 EST

Generally one needs to know 2-4 static methods to create a simple custom widget, plus the API of 2-3 objects (adapter, serverObject and the parent). All of this already exists in some form, but it might be a good idea to create a simple facade to group the static methods.

These are:
* rwt.protocol.AdapterRegistry.add
  -> registering the widget
* rwt.protocol.ServerObjectFactory.getServerObject 
  -> get ServerObject to send messages to the Server
* rwt.protocol.AdapterUtil.callWithTarget
  -> required to attach to the parent widget
* rwt.protocol.ObjectRegistry.getObject
  -> required if an protocol-id is to be send to the server as a parameter

The "callWithTarget" and "getObject" methods may not be needed if we somehow solve their usecases within the adapter/serverObject.

Since a custom widget should be based on dom-elements, (not extending any internal widgets), we also need a way to add those to a parent. The most simple way would be to modify Parent.js#add to accept html elements, but we could also try to find a solution that also eliminates callWithTarget. 

The facade could be placed either within our normal namespace-objects (rwt.*), or be a global object like "rap". I don't want to abuse the objects we use as a namespace and place functions in there.

The serverObject API might also need to be discussed. There are some details i'm currently not happy with.

Comment 2 Tim Buschtoens 2012-12-05 08:20:26 EST

A provisional API has been introduced with commit 749aed413a290955d3f0e91a7974333baaf190b6. A first draft for an API reference and custom widget tutorial can be found here: https://github.com/tbuschto/customWidgetTemplate/wiki/_pages

Comment 3 Tim Buschtoens 2012-12-05 08:55:01 EST

We could use jsdoc (http://code.google.com/p/jsdoc-toolkit/) to generate an API reference at least for the "rap" object and possibly for the RemoteObject. Not sure if/how it could work for the protocol-adapter/type-handler interface.

I tried it, and it works very well for me. Example:

/**
 * @namespace Holds all public API of the RAP WebClient.
 */
rap = {

  /**
   * @description Used to register RAP type handler
   * @param {String} type
   * @param {Object} handler
   */
  registerTypeHandler : function( type, handler ) {
....

Comment 4 Tim Buschtoens 2012-12-11 06:18:35 EST

Added JsDoc for rap.js and ServerObject.js with commit 395bea5e5b41fadae1918ff8d64ce0f9d0ed958c.

Comment 5 Ralf Sternberg 2013-03-07 09:30:48 EST

With RAP 2.0, a minimal JS API has been published:
http://download.eclipse.org/rt/rap/doc/2.0/guide/reference/jsdoc/index.html