How to create a custom widget?

After having a brief overview of the principles of the Life Cycle Adapter let's start by implementing the LCA for our GMap widget. After creating the LCA class - which extends AbstractWidgetLCA - we will fill the interesting methods with some logic. First comes the initialization.

  
  public void renderInitialization( Widget widget ) throws IOException {
    JSWriter writer = JSWriter.getWriterFor( widget );
    String id = WidgetUtil.getId( widget );
    writer.newWidget( "org.eclipse.rap.gmaps.GMap", new Object[] { id } );
    writer.set( "appearance", "composite" );
    writer.set( "overflow", "hidden" );
    ControlLCAUtil.writeStyleFlags( ( GMap )widget );
  }
  
  

Basically the class JSWriter is responsible for transforming our java calls and setters into the corresponding javascript which gets transfered to the client. The JSWriter is also responsible to only write out changes which are different than their preserved value. For each widget you have an own JSWriter instance so RAP can decide to which widget the call belongs. As you can see in the snippet, JSWriter#newWidget is called to create a new widget on the client side. The second parameters is an array of Objects which are passed to the constructor of the qooxdoo class (see above). With JSWriter#set you can easily set different attributes of your qooxdoo object. This could also be done in Javascript and is just a showcase in here. The next step is to preserve our values therewith RAP can decide in the next request if there has something changed in the meantime. As we just have the address which could change this is relative straight forward.

  
  private static final String PROP_ADDRESS = "address";
  
  public void preserveValues( Widget widget ) {
    ControlLCAUtil.preserveValues( ( Control )widget );
    IWidgetAdapter adapter = WidgetUtil.getAdapter( widget );
    adapter.preserve( PROP_ADDRESS, ( ( GMap )widget ).getAddress() );
    
    // only needed for custom variants (themeing)
    WidgetLCAUtil.preserveCustomVariant( widget );
  }
  
  

First we use ControlLCAUtil#preserveValues to have most of the work done by the framework. It's responsible for preserving values like tooltip, tabindex, size, etc. So we only need to care about the things implemented in our widget. We just request a so called IWidgetAdapter which is responsible for different aspects in the lifecycle of a widget. In this case we only use it to preserve the address value with a predefined key (PROP_ADRESS) to associate it later.
The last line calling preserveCustomVariant is only added for the sake of completeness. Variants is a way to have different looks of the same widget and is part of the theme engine provided by RAP. Please see the Prepare Custom Widgets for Theming article for more informations about theming a custom widget.

The following step is one of most interesting parts of your lifecycle adapter - the renderChanges method. As said before it is responsible to write every change to the outgoing stream which is executed on the client. Let's take a look at the implementation:

  
  private static final String JS_PROP_ADDRESS = "address";
  
  public void renderChanges( Widget widget ) throws IOException {
    GMap gmap = ( GMap )widget;
    ControlLCAUtil.writeChanges( gmap );
    JSWriter writer = JSWriter.getWriterFor( widget );
    writer.set( PROP_ADDRESS, JS_PROP_ADDRESS, gmap.getAddress() );
    
    // only needed for custom variants (themeing)
    WidgetLCAUtil.writeCustomVariant( widget );
  }
  
  

Again we use the ControlLCAUtil to write the changes which are implemented on Control and thus we should not care what's behind it (for those who really want to know it - it's the same as preserving the values like tooltip, tabindex, size, etc). Like in the widget initialization we have to render something and therefore we need to obtain the corresponding JSWriter instance for our widget. We need to use JSWriter#set to set a specific attribute to the widget instance on the client-side. There are many different set implementations available for every need. The one used here is simple: We pass the key for the preserved value to the method so RAP can check if there has something changed since the last time it was preserved, we pass the name of the client-side attribute which gets transformed into "set*" and last but not least the value for this setter. As we can see, the name of the javascript attribute (JS_PROP_ADRESS) will call the method setAdress on the corresponding widget instance on the client. If you wonder where this method is, take a look at the qooxdoo property system. The address property of our widget will be transformed by qooxdoo into a set* and get* methods at runtime.

Now we need to process the actions transfered to the server (at least if there are any). We see in the GMap.js that if the user moves the map a new parameter called centerLocation will be attached to the current request and transfered to the server. To read and process it the readData method of the LCA is used.

  
  private static final String PARAM_CENTER = "centerLocation";
  
  public void readData( Widget widget ) {
    GMap map = ( GMap )widget;
    String location = WidgetLCAUtil.readPropertyValue( map, PARAM_CENTER );
    map.setCenterLocation( location );
  }
  
  

As you can see, it's really easy. You just need to ask the WidgetLCAUtil#readPropertyValue for the parameter and pass it to the server-side widget implementation. If you wonder why the center location does not get written in the renderChanges method we implemented above: This will be your task at the end of the tutorial. Normally you won't have public methods for attributes which are not changeable programmatically. For this you would use an adapter or another mechanism to implement the setter behind the scenes. At the end of the tutorial it is your task hide the public setCenterLocation method of the GMap widget or - even better - to implement the rendering of the center location yourself.

The last step is to implement the way our widget is disposed on the client. Normally there is no need to care for anything else and this is also the case with our GMap widget. If you really have to do any other stuff like calling specific methods before the widget is disposed you should do it here.

  
  public void renderDispose( Widget widget ) throws IOException {
    JSWriter writer = JSWriter.getWriterFor( widget );
    writer.dispose();
  }
  
  

There are now two additional methods called createResetHandlerCalls and getTypePoolId. These were introduced by a mechanism that helps to soften the massive memory consumption on the client. Many of the client-side widgets are not thrown away anymore, but kept in an object pool for later reuse. Especially with long-running applications in the Internet Explorer browser, this can make a huge difference. Please note that this topic is work in progress and, despite extensive testing, might lead to errors under different circumstances. We recommend not to use this in your custom widgets.

Registering the javascript files

  
  <plugin>
    <extension
      id="org.eclipse.rap.gmaps.gmap"
      point="org.eclipse.rap.ui.resources">
        <resource class="org.eclipse.rap.gmaps.GMapResource"/>
        <resource class="org.eclipse.rap.gmaps.GMapAPIResource"/>
    </extension>
  </plugin>
  
  

Both classes refer to an implementation of org.eclipse.rwt.resources.IResource. The first one - our custom widget itself - is really easy to implement. We just need to tell RAP that it is a javascript file, where it can find the file and which charset to use. So the IResource> implementation for the widget javascript could look like this:

  
  public class GMapResource implements IResource {
  
    public String getCharset() {
      return "ISO-8859-1";
    }
  
    public ClassLoader getLoader() {
      return this.getClass().getClassLoader();
    }
  
    public RegisterOptions getOptions() {
      return RegisterOptions.VERSION_AND_COMPRESS;
    }
  
    public String getLocation() {
      return "org/eclipse/rap/gmaps/GMap.js";
    }
  
    public boolean isJSLibrary() {
      return true;
    }
  
    public boolean isExternal() {
      return false;
    }
  }
  
  

For the charset we need to return a string to describe the charset. If you're not sure you can use of the constants defined in org.eclipse.rwt.internal.util.HTML but be aware that this is internal. The getOptions method specifies if the file should be delivered with any special treatment. Possible ways are NONE, VERSION, COMPRESS and VERSION_AND_COMPRESS. VERSION means that RAP will append a hash value of the file itself to tell the browser if he should use an already cached version or reload the file from the server. With the COMPRESS option RAP will remove all unnecessary stuff like blank lines or comments from the javascript file in order to save bandwidth and parse time. Remote files like our next task - the Google Maps library - are handled a little bit different.

  
  public class GMapAPIResource implements IResource {
  
    private static final String KEY_SYSTEM_PROPERTY = "org.eclipse.rap.gmaps.key";
    
    // key for localhost rap development on port 9090
    private static final String KEY_LOCALHOST
    = "ABQIAAAAjE6itH-9WA-8yJZ7sZwmpRQz5JJ2zPi3YI9JDWBFF"
        + "6NSsxhe4BSfeni5VUSx3dQc8mIEknSiG9EwaQ";
    
    private String location;
    
    public String getCharset() {
      return "ISO-8859-1";
    }
  
    public ClassLoader getLoader() {
      return this.getClass().getClassLoader();
    }
  
    public RegisterOptions getOptions() {
      return RegisterOptions.VERSION;
    }
  
    public String getLocation() {
      if( location == null ) {
        String key = System.getProperty( KEY_SYSTEM_PROPERTY );
        if( key == null ) {
          key = KEY_LOCALHOST;
        }
        location = "https://maps.google.com/maps?file=api&v=2&key=" + key; 
      }
      return location;
    }
  
    public boolean isJSLibrary() {
      return true;
    }
  
    public boolean isExternal() {
      return true;
    }
  }
  
  

To tell RAP to load external resources we just need to return true in isExternal. The location should be a valid URL where the resource resides. In this case it's loaded from the Google Maps server with a special API key. This is specific for the Google Maps widget and is not needed by other widgets. If you're planning to use or extend this sample widget we encourage you to get your own API key for Google as this key will only work on https://localhost:9090/rap. With every other combination of host, port or servletName you need to obtain a new key. Additionally we implemented a system property to define the key without recompiling the widget.
We've just finished our custom widget and our project structure should look like this if we have done everything right.

Test the widget

In order to test the widget we will create a new plug-in project with the following entrypoint:

  
  public class GMapDemo implements IEntryPoint {

    public int createUI() {
      Display display = new Display();
      Shell shell = new Shell( display, SWT.SHELL_TRIM );
      shell.setLayout( new FillLayout() );
      shell.setText( "GMaps Demo" );
      
      GMap map = new GMap( shell, SWT.NONE );
      map.setAddress( "Stephanienstra�e 20, Karlsruhe" );
  
      shell.setSize( 300, 300 );
      shell.open();
      while( !shell.isDisposed() ) {
        if( !display.readAndDispatch() ) {
          display.sleep();
        }
      }
      return 0;
    }
  }
  
  

Don't forget to add org.eclipse.rap.ui and the GMap widget project as dependencies. Then we need to register our entry point via the org.eclipse.rap.ui.entrypoint. If everything went well our demo should look like this after starting the server:

But there was more: the center location we sended to the server. To read it out, we extend the sample with a new button:

  
  public class GMapDemo implements IEntryPoint {

    public int createUI() {
      Display display = new Display();
      final Shell shell = new Shell( display, SWT.SHELL_TRIM );
      shell.setLayout( new FillLayout() );
      shell.setText( "GMaps Demo" );
      
      GMap map = new GMap( shell, SWT.NONE );
      map.setAddress( "Stephanienstra�e 20, Karlsruhe" );
  
      Button button = new Button( shell, SWT.PUSH );
      button.setText( "Tell me where I am!" );
      button.addSelectionListener( new SelectionAdapter() {
        public void widgetSelected( SelectionEvent e ) {
          String msg = "You are here: " + map.getCenterLocation() 
          MessageDialog.openInformation( shell, "GMap Demo", msg );
        }
      });
      
      shell.setSize( 300, 300 );
      shell.open();
      while( !shell.isDisposed() ) {
        if( !display.readAndDispatch() ) {
          display.sleep();
        }
      }
      return 0;
    }
  }
  
  

After a click on the button the current location will be sended to the server (together with the selection event of the button), applied to the widget with the help of our LCA and shown by the MessageDialog. Great!

And now?

You completed your first custom widget - congratulations!
Before implementing a heavy custom control we like to give you some tasks to play around with the GMap widget.

• Implement the rendering for the center location to programmatically set it
• Add support for markers
• Implement other nice things by connecting Google Maps with RAP

Troubleshooting

There may be times where you need to track down a javascript error in your custom widget. As the tooling support for javascript is not that mature as for java we provide some little undertakes to help you debugging your custom widget.

Client library variants

Client log level

To see debug messages and exceptions which occured during javascript execution you can turn on the client-side debugging mode with -Dorg.eclipse.rwt.clientLogLevel=<LEVEL> where <LEVEL> is one of the following values:

• OFF
• ALL
• WARNING
• INFO
• SEVERE
• FINE
• FINER
• FINEST

When developing custom widget we recommend to use the level ALL to see every debug message.