Eclipse RAP : Custom Widget development

It took a while to understand and create a custom widget but finally i could do it. I wanted to create a custom widget to draw sequence of svg graphics. I followed the Custom widget development at the RAP help site. It helped me to get a good start but since i was trying to do SVG it didnt really work at my first attempt..(i know... nothing works at the first attempt).

The SVG support i wanted to create was something like below.



Here is what i did to create a custom widget.

1. Create a new plugin project and name it like com.xyz.project.mywidget
This is not mandatory but its good to call the plugin as the widget name.

2. Create a package com.xyz.project.mywidget
This package will contain the server side, client side and API resource classes. Just follow as explained in the RAP help.

3. Create the server side Widget class , i wanted a widget to send events to the server and also behave as a selection provider when a image is clicked. So i extended SWT Composite and implemented ISelectionProvider.

public class MyWidget extends Composite implements ISelectionProvider {

 /**
  * for showing multiple images on the widget
  */
 private String[] images;

 /**
  * To get the selection back from the client.
  */
 int selectionIndex;

 /**
  * Listeners
  */
 private ListenerList listeners = new ListenerList();

 /**
  * Selection.
  */
 private ISelection selection;

 private String selectedImage;

 public MyWidget(Composite parent) {
  super(parent, SWT.NONE);
 }

 public String[] getImages() {
  return images;
 }

 public void setImages(String[] parts) {
  this.images = parts;
 }

 @Override
 public void setLayout(Layout layout) {
  super.setLayout(new FillLayout());
 }

 public String getSelectedImage() {
  return selectedImage;
 }

 public void setSelectedImage(String selectedPart) {
  this.selectedImage = selectedPart;
  if (selectedPart != null) {
   selectionIndex = Integer.parseInt(selectedPart);
   setSelection(new StructuredSelection(images[selectionIndex / 2]));
  }
 }

 public void addSelectionChangedListener(ISelectionChangedListener listener) {
  listeners.add(listener);
 }

 public ISelection getSelection() {
  return selection;
 }

 public void removeSelectionChangedListener(
   ISelectionChangedListener listener) {
  listeners.remove(listener);
 }

 public void setSelection(ISelection selection) {
  this.selection = selection;
  Object[] list = listeners.getListeners();
  for (int i = 0; i < list.length; i++) {
   ((ISelectionChangedListener) list[i])
     .selectionChanged(new SelectionChangedEvent(this, selection));
  }
 }
}

Follow this post for how to implement ISelectionProvider - http://random-eclipse-tips.blogspot.com/2009/02/eclipse-how-to-implement.html

Now that the server side, widget is ready, we need the client side widget code, the qooxdoo javascript code. Read the qooxdoo explanation in RAP custom widget tutorial and follow it, it gives you a basic idea of what to do.

    qx.Class.define( "com.xyz.project.MyWidget", {
    extend: qx.ui.layout.CanvasLayout,
      
    construct: function( id ) {
            this.base( arguments );
            this.setHtmlAttribute("id",id);
            this._id = id; 
 },
 
 properties : {
     images : {
            init : "",
            apply : "load"
      },

   members : { 
     load : function() {
      var current = this.getParts()[0];
         if( current != null && current != "" ) {
          qx.ui.core.Widget.flushGlobalQueues();
          var id = document.getElementById( this._id );
          var wm = org.eclipse.swt.WidgetManager.getInstance();
                var designWidgetId = wm.findIdByWidget( this);
    var newParts = this.getParts();     
    var current = null;
    var image = 1;
    if(this.__paper == null ) {
     this.__paper = Raphael(id, newParts.length*100, 480);
    startx = 10;
    starty = 10;
    width = 100;
    height=25;
    curve=10;
    var part=0, colorhue = .6 || Math.random(),    
          color = "hsb(" + [colorhue, 1, .75] + ")";
    var selectionColor = "#d54";
    var currentSelection = null;
    var detail = this.__paper.rect(startx, starty+height+5, 200, 100, 5).attr({fill: "#d54" , stroke: "#474", "stroke-width": 2}).hide();       
    label0 = this.__paper.text(startx+20,starty+height+10,"ID : ").hide();
    label1 = this.__paper.text(startx+20,starty+height+25,"Other : ").hide();
    for (part=0;part<newParts.length;part++)  
    {
      (function(paper,part,type){
         var c = "#ccc";
         if(image==0) {
          if(type == "image1") {
           paper.image("./Part_icon_image1.png", startx, starty, width, height);
          }else if(type == "image2") {
           image("./Part_icon_image2.png", startx, starty, width, height);
          }    
         }         
         var label = paper.text(startx+25,starty+10,part).hide();
         paper.rect(startx,starty,width,height,curve).attr({stroke: c, fill: c, "fill-opacity": .4}).
         mouseover(
           function(){
            this.animate({"fill-opacity": .75}, 500);           
            detail.show().animate({x: 10+(width*part), y: starty+height+5}, 200 );
            label0.attr({text: "ID : "+newParts[part]}).show().animate({x: 40+(width*part), y: starty+height+10}, 200);
            label1.attr({text: "Other : "}).show().animate({x: 40+(width*part), y: starty+height+25}, 200);
            paper.safari();
           }).
         mouseout(
           function(){              
            this.animate({"fill-opacity": .25}, 500);           
            detail.hide();
            label0.hide();
            label1.hide();
            paper.safari();
           }).
         click(
           function(){
            if(currentSelection != null ) {
             currentSelection.attr({fill:c});
            }
            currentSelection = this;
            currentSelection.attr({fill:selectionColor});
            var req = org.eclipse.swt.Request.getInstance();            
                  req.addParameter( designWidgetId +".selectedImage", part );  
                  req.send();
           });
        })(this.__paper,part,newParts[part]);         
        startx+=width;        
       }       
         }}        
         
     },    
 }
});

Now that, whenever the setImages method is called on the server side widget, the client has to update the browser. But how does it interact, the server side widget and the client side widget get connected through two main classes, the API resource class and the LCA class. There are different ways of defining the LCA class but here i would just follow the simple approach as explained in the RAP help.

First to create the API resource, we need to create a IResource implementation , In our case, MyWidgetResource as follows,

public class DesignWidgetResource implements IResource {
 public String getCharset() {
  return HTML.CHARSET_NAME_ISO_8859_1;
 }

 public ClassLoader getLoader() {
  return this.getClass().getClassLoader();
 }

 public RegisterOptions getOptions() {
  return RegisterOptions.VERSION_AND_COMPRESS;
 }

 public String getLocation() {
  return "com/xyz/project/mywidget/MyWidget.js";
 }

 public boolean isJSLibrary() {
  return true;
 }

 public boolean isExternal() {
  return false;
 }
}

you can just copy and paste the above code and replace the getLocation method to your .js file. Now the LCA, this can either be written in a pre defined package or can be done using getAdapter method in the widget class. I will follow the pre defined package which com.xyz.project.mywidget.internal.mywidgetkit and create MyWidgetLCA.java

public class MyWidgetLCA extends AbstractWidgetLCA {

 private static final String PARAM_SELECTED = "selectedImage";

 private static final String PROP_IMAGES = "images";

 private static final String JS_PROP_IMAGE = "images";

 public void preserveValues(final Widget widget) {
  ControlLCAUtil.preserveValues((Control) widget);
  IWidgetAdapter adapter = WidgetUtil.getAdapter(widget);
  adapter.preserve(PROP_IMAGES, ((MyWidget) widget).getImages());
  // adapter.preserve(PROP_MOVE_RIGHT, ((DesignWidget) widget)
  // .getMoveRight());
  // only needed for custom variants (theming)
  WidgetLCAUtil.preserveCustomVariant(widget);
 }

 /*
  * Read the parameters transfered from the client
  */
 public void readData(final Widget widget) {
  MyWidget myWidget = (MyWidget) widget;
  String location = WidgetLCAUtil.readPropertyValue(myWidget,
    PARAM_SELECTED);
  myWidget.setSelectedImage(location);
 }

 /*
  * Initial creation procedure of the widget
  */
 public void renderInitialization(final Widget widget) throws IOException {
  JSWriter writer = JSWriter.getWriterFor(widget);
  String id = WidgetUtil.getId(widget);
  writer.newWidget("com.xyz.project.mywidget.MyWidget",
    new Object[] { id });
  writer.set("appearance", "composite");
  writer.set("overflow", "hidden");
  ControlLCAUtil.writeStyleFlags((MyWidget) widget);
 }

 public void renderChanges(final Widget widget) throws IOException {
  MyWidget gmap = (MyWidget) widget;
  ControlLCAUtil.writeChanges(gmap);
  JSWriter writer = JSWriter.getWriterFor(widget);
  writer.set(PROP_IMAGES, JS_PROP_IMAGE, gmap.getImages());
  // only needed for custom variants (theming)
  WidgetLCAUtil.writeCustomVariant(widget);
 }

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

 public void createResetHandlerCalls(String typePoolId) throws IOException {
 }

 public String getTypePoolId(Widget widget) {
  return null;
 }

}

Here, the LCA class is the important class which communicates between the server code and client script. The selection on the client sends an event to the server through the LCA in the readData method. The client code will use org.eclipse.swt.Request.getInstance() to send the request to the server when an image is clicked on the Widget.

Now we got the both the resource and LCA ready. we need to create an resources extension point and add the MyWidgetResource classes.

   <extension
         point="org.eclipse.rap.ui.resources">
      <resource
            class="com.xyz.project.mywidget.MyWidgetResource">
      </resource>
   </extension>

ok..we have a basic setup ready, what is the Raphael stuff on the Qooxdoo javascript. Raphael is a Javascript based SVG library which helps creating different SVG based graphics. For more details on that visit http://raphaeljs.com/. The demos explain a lot about the library. How do we add an external javascript resource into the myWidget implementation.

1. Create a RaphaelAPIResource similar to the one we created for MyWidget as MyWidgetResource.

public class RaphaelAPIResource implements IResource {

 private String location;

 public String getCharset() {
  return HTML.CHARSET_NAME_ISO_8859_1;
 }

 public ClassLoader getLoader() {
  return this.getClass().getClassLoader();
 }

 public String getLocation() {
  location = "http://raphaeljs.com/raphael.js";
  return location;
 }

 public RegisterOptions getOptions() {
  return RegisterOptions.VERSION;
 }

 public boolean isExternal() {
  return true;
 }

 public boolean isJSLibrary() {
  return true;
 }

}

and add the resources extension to the existing extension point we used as following.

   <extension
         point="org.eclipse.rap.ui.resources">
      <resource
            class="com.biologistics.gd.design.RaphaelAPIResource">
      </resource>
      <resource
            class="com.biologistics.gd.design.DesignWidgetResource">
      </resource>
   </extension>

Since we are displaying images on the client side , we need the images also as resources sent to the client. we have to create http.registryresources to use aliases for the images. In this case, we are referring to Part_icon_image1.png and Part_icon_image2.png as alias in the javascript.

 <extension
         point="org.eclipse.equinox.http.registry.resources">
      <resource
            alias="/Part_icon_image1.png"
            base-name="branding/Part_icon_image1.png">
      </resource>
      <resource
            alias="/Part_icon_image2.png"
            base-name="original/Part_icon_image2.png">
      </resource>
 </extension>

Now we can create a view with MyWidget as a child and setImages on that.

 public void createPartControl(final Composite parent) {
  widget = new MyWidget(parent);
  widget.setParts(new String[]{"image1","image2"});
  getSite().setSelectionProvider(widget); 
 }

Will be glad to help !