Building a GWT Declarative Interface

Introduction

GWT 2 has introduced the concept of declarative interfaces, that is, the interface can be described via an XML document, rather than built using code. The idea isn't new, it's seen in many new technologies such as Macromedia Flex, ASP.Net and JavaFX, however to the GWT developer it means the end of writing reams of boiler plate code.

In this post I show you how to create a simple Image Gallery widget that has a declarative interface and then how to create bigger interfaces using these widgets.

The Basic Widget

Before we do anything, we need to define the basic ImageGalleryWidget, in our case, it looks as so :

public class ImageGalleryWidget extends Composite {
 private GalleryImage[] images;
 private int currentImageIndex = 0;
 
 public ImageGalleryWidget() {
 }
 
 public void setTitle(String value) {
 }
 
 public void setImages(GalleryImage[] images) {
  this.images = images;
  currentImageIndex = 0;
 }
 
 public static class GalleryImage {
  private final String caption;
  private final String url;
  
  public GalleryImage(String url, String caption) {
   this.caption = caption;
   this.url = url;
  }
  
  public String getUrl() {
   return url;
  }
  
  public String getCaption() {
   return caption;
  }
 }
}

As you can see, our ImageGallery has two properties: a title, and an array of images to display. Each image has the URL of the actual file, and a caption. You'll also notice that our widget doesn't extend Widget but rather Composite, this is important as we'll see later.

Defining the Interface

GWT allows you to use the declerative method to define interfaces of individual components, in this case the interface for a particular widget. Before we go any further, it would be a good idea to show the UI for our image gallery:

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder' 
      xmlns:g='urn:import:com.google.gwt.user.client.ui'>

  <g:VerticalPanel spacing="3">
   <g:Cell horizontalAlign="CENTER" cellSpacing="40" width="100%">
    <g:Label ui:field="title"/>
   </g:Cell>
   <g:Cell>
    <g:Image ui:field="image"/>
 </g:Cell>
 <g:Cell width="500px">
    <g:HorizontalPanel spacing="5" width="100%">
     <g:Cell>
      <g:Button text="Prev" ui:field="btnPrev"/>
     </g:Cell>
     <g:Cell>
      <g:Label ui:field="caption"/>
     </g:Cell>     
     <g:Cell>
      <g:Button text="Next" ui:field="btnNext"/>
     </g:Cell>
    </g:HorizontalPanel>
 </g:Cell>  
  </g:VerticalPanel>
</ui:UiBinder>

First lets look at the namespace declarations. The first binds the prefix ui to urn:ui:com.google.gwt.uibinder which identifies GWT specific elements to the parser such as the UiBinder element; it will be required on every declared interface file. The next namespace urn:import:com.google.gwt.user.client.ui imports elements from the com.google.gwt.user.client.ui package, (the standard GWT Widget package) to be used in the interface. You can see some of these objects in use such as g:VerticalPanel. We'll come back to imported elements later.

Inside the UiBinder element you define your interface by specifying widgets to be instantiated. In this case we're creating a standard VerticalPanel widget with Cells for each row. In the top cell we're adding a label, the next we're adding an Image, and the bottom cell holds a HorizontalPanel which contains the Prev and Next buttons. As you'll appreciate, this interface file is a lot easier to read and modify than if it had been defined in standard Java.

Certain elements in our file have a special ui:field attribute defined. This is a special declarative attribute which tells GWT which field within the associated Java class (we'll get to that shortly), should hold a reference to that component.

Our widget is called ImageGalleryWidget and therefore the declarative XML file should be saved in the same package with the name ie. ImageGalleryWidget.ui.xml

Binding To A Java Class

The XML defines the UI, however a UI doesn't exist by itself, we need a way of referencing elements so that we can set and retrieve properties. In order to do this we need to add elements to the ImageGalleryWidget :

public class ImageGalleryWidget extends Composite {
 interface ImageGalleryUiBinder extends UiBinder<VerticalPanel, ImageGalleryWidget> {}
 private static ImageGalleryUiBinder uiBinder = GWT.create(ImageGalleryUiBinder.class);
 
 @UiField Image image;
 @UiField Label caption, title;
 @UiField Button btnNext, btnPrev; 

 // .... Rest Ignored ... 
} 

The first line defines an interface which will act as the binder, that is, it will set the field elements annotated by UiField. An implementation of this interface will be created by the GWT compiler. The second line is a standard GWT deferred binding create statement need to instantiate the generated binder class.

The next thing we need to do is perform the binding magic to apply values to our UiFields. This is done using the binder as so :

 public ImageGalleryWidget() {
  initWidget(uiBinder.createAndBindUi(this));
 }

Here, the binder instance, created using deferred binding, is told to bind the interface file elements to the UiField elements in this class. The return from this call is a VerticalPanel, which if you remember, is the root panel from our UI XML. If this was a standard Widget, we'd only be able to set an Element, however, because this is a Composite Widget, we're able to set a child widget using initWidget method.

NOTE: The name of the field in the class being bound to MUST be exactly the same as the ui:field entry, including case.

Now we have UI element bindings, we can treat this as if the UI had been created using the standard Java approach. Here, for example, are the setTitle and setImages methods :

 public void setTitle(String value) {
  title.setText(value);
 }
 
 public void setImages(GalleryImage[] images) {
  this.images = images;
  currentImageIndex = 0;
  displayImage();
 }
  
 private void displayImage() {
  image.setUrl(images[currentImageIndex].getUrl());
  image.setTitle(images[currentImageIndex].getCaption());
  caption.setText(images[currentImageIndex].getCaption());
 }

Adding Event Handlers

As it stands, our image gallery would simply display the first image in the array, what we need to do now is listen for Click events on the Prev and Next buttons in order to display other images.

In standard GWT we'd have to add anonymous ClickHandlers, but with the declarative interface we can use features of the generated UiBinder to do the work for us. For example, here's the click handlers for the buttons:

 @UiHandler("btnPrev")
 public void handlePrev(ClickEvent event) {
  if (currentImageIndex != 0) {
   currentImageIndex--;
   displayImage();
  }
 }

 @UiHandler("btnNext")
 public void handleNext(ClickEvent event) {
  if (currentImageIndex != images.length -1) {
   currentImageIndex++;
   displayImage();
  } 
 } 

In both cases, the UiHandler annotation tells GWT which UiField field this handler is for. The name of the method itself doesn't matter, it can be anything you like. In order to set the handler, GWT will look at the event and discover the name of the Handler class. It will then look for a method call add on the widget the event is being bound to. For example, if we had an event called MySimpleEvent that had an associated handler called MySimpleHandler, GWT would look for a method called addMySimpleHandler on the Widget specified in the UiHandler annotation.

A Quick Test

Before we go any further, it would be good to test this Widget. Here's an example of using the Widget, using photos from Flickr

public class UIBinderExample implements EntryPoint {

 private static final GalleryImage[] images = {
 new GalleryImage("http://farm4.static.flickr.com/3309/3622157565_fd079ac983.jpg","Bishop's Moat"),
 new GalleryImage("http://farm2.static.flickr.com/1257/928632149_71d88ac137.jpg","Family Of Goats"),
 new GalleryImage("http://farm1.static.flickr.com/61/193636096_1f34d7a78d.jpg","Wooden Boat - Sailing - Port Townsend")};
 
 public void onModuleLoad() {
  ImageGalleryWidget widget = new ImageGalleryWidget();
  widget.setImages(images);
  widget.setTitle("Sample Flickr Gallery");
    
  RootPanel.get().add(widget);
 }
}

Adding Style

At the moment the widget doesn't look very good; let's improve that by adding some CSS styles. To do this we first add a ui:Style element to our UI definition.

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder' 
    xmlns:g='urn:import:com.google.gwt.user.client.ui'>

  <ui:style>
   .caption {font-weight:bold;width:100%}
   .button {color:red}
   .image {width:375px; height:500px}
  </ui:style>
  
  <!-- Rest Ignored -->
</ui:UiBinder>

We can then use those styles by setting the styleName property of the relevant elements, ie :

   <g:Cell>
    <g:Image styleName="{style.image}" ui:field="image"/>
 </g:Cell>

Reusing this Widget

GWT allows you to build up your UI using different definition files. What we'll do now is reuse this initial Widget in a new UI that is itself declared using XML. In order to do this we'll define a UI that uses two versions of this Image Gallery, and looks like so

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder' 
    xmlns:g='urn:import:com.google.gwt.user.client.ui'
    xmlns:d='urn:import:com.maddison.client.widgets'>
    
 <g:HorizontalPanel spacing="5" width="100%">
  <g:Cell>
   <d:ImageGalleryWidget title="Gallery One" ui:field="galleryOne"/>
  </g:Cell>
  <g:Cell>
   <d:ImageGalleryWidget title="Gallery Two" ui:field="galleryTwo"/>
  </g:Cell>
 </g:HorizontalPanel>    
</ui:UiBinder>

The important part of this file is the urn:import:com.maddison.client.widgets namespace declaration. This states that widgets marked with the d namespace can be found in the com.maddison.client.widgets package. Properties on this Widget (for example the title) are set by calling a setXXX method on the given widget.

To show another feature of the declarive API, lets save this file as MainAppInterface.ui.xml. Our application will be defined in a Composite widget that looks like so :

public class MyApp extends Composite {
 @UiTemplate("MainAppInterface.ui.xml")
 interface MyAppUiBinder extends UiBinder<HorizontalPanel, MyApp> {}
 private static MyAppUiBinder uiBinder = GWT.create(MyAppUiBinder.class);

 private static final GalleryImage[] images = {
  new GalleryImage("http://farm4.static.flickr.com/3309/3622157565_fd079ac983.jpg","Bishop's Moat"),
  new GalleryImage("http://farm2.static.flickr.com/1257/928632149_71d88ac137.jpg","Family Of Goats"),
  new GalleryImage("http://farm1.static.flickr.com/61/193636096_1f34d7a78d.jpg","Wooden Boat - Sailing - Port Townsend")};
  
 
 @UiField ImageGalleryWidget galleryOne, galleryTwo;
 
 public MyApp() {
  initWidget(uiBinder.createAndBindUi(this));
  galleryOne.setImages(images);
  galleryTwo.setImages(images);
 }
}

You'll notice the UiTemplate annotation above the MyAppUiBinder interface. Normally GWT will look for a UI definition file that has the same name as the parent class, however, in this case we've told GWT that the interface file is actually called MainAppInterface.ui.xml by using the annotation.

Final Test

Our final application simply has to instantiate the MyApp interface like so:

public class UIBinderExample implements EntryPoint { 
 public void onModuleLoad() {
  RootPanel.get().add(new MyApp());
 }
}

Conclusion

Hopefully this post has shown how to use some features of the GWT declarative UI, by no means does it show everything that's possible!

A complete Eclipse project with all the code from this post can be found here

Using GWT 2 Custom Events

Introduction

In a previous post I showed how to create a custom GWT component based on GWT 1.7. In this post I'll show you how to perform the same thing using GWT 2's new event system. In order to make clear how custom GWT events are built, I'll be doing things slightly differently in that we'll be building it in a Model-Binder-View style.

The Model

The model is where we're going to concentrate on the majority of our effort as this is the component that will be generating the custom events. There's nothing special in the basic model class, it looks like this :

public class ListModel {
 final private List<ListItem> items = new ArrayList<ListItem>();

 public void addItem(ListItem item) {
  items.add(item);
 }
 
 public void removeItem(ListItem item) {
  items.remove(item);
 }
 
 public void removeAll() {
  items.clear();
 }
 
 public List getItems() {
  return Collections.unmodifiableList(items);
 }
}

Java Tip:Notice here that when we return the list of items, we wrap it in an UnmodifiableList. This makes the list immutable and thus stops any clients modifying the model state outside of our component.

The ListItem class looks like this:

public class ListItem {
 private final String text;
  
 public ListItem(String text) {
  this.text = text;
 }
 
 public String getText() {
  return text;
 }
  
        // Equals and HashCode hidden
}

In this example, ListItem is simply a wrapper around some text. We could use a string for the ListItem, but this method allows a user of the model to extend ListItem to include any extra required information (for example, adding a map of values).

Adding the HandlerManager

At this point our model isn't very reactive, a client would have to poll the model in order to see any changes. What we'll do now is fire an event when an item is added. In GWT 1.x this had to be done using listeners, however GWT 2 provides out of the box support for handling event registration and notification in the form of the com.google.gwt.event.shared.HandlerManager.

Adding the HandlerManager to our ListModel is straight forward, here's the HandlerManager added to the top of our class:

public class ListModel {
 final private HandlerManager handlerManager = new HandlerManager(this);
 final private List items = new ArrayList();
 
 // Other code hidden
} 

Notice that HandlerManager takes an object as it's constructor. The Object passed in is used as the source of all events this HandlerManager will fire.

The ItemAdded event

Events in GWT 2 come in two parts, a class that extends GWTEvent (the event object) and an interface that extends EventHandler (the handler interface). The event handler interface is the easiest to understand as EventHandler is simply a marker interface. The EventHandler for ItemAdded looks like so:

public interface ItemAddedHandler extends EventHandler {

 void onItemAdded(ItemAddedEvent event);
} 

The ItemAddedEvent class looks like so:

public class ItemAddedEvent extends GwtEvent<ItemAddedHandler> {
 private static final Type TYPE = new Type<ItemAddedHandler>();
 
 private final ListItem listItem;
 
 public ItemAddedEvent(ListItem listItem) {
  this.listItem = listItem;
 }
 
 public static Type getType() {
  return TYPE;
 }
 
 /** @returns The item added to the model */
 public ListItem getListItem() {
  return listItem;
 }
 
 @Override
 protected void dispatch(ItemAddedHandler handler) {
  handler.onItemAdded(this);
 }

 @Override
 public com.google.gwt.event.shared.GwtEvent.Type getAssociatedType() {
  return TYPE;
 }
}

The event object is slightly confusing because it fulfills two roles. On the one hand it's the object which the ListItem so that the handler can retrieve it when it's notified. On the other hand the event object also acts as the dispatcher for the given event.

Firing the event

Using these two new classes, when an item is added to our model, we can now fire the event. The following code shows the amended addItem method:

 public void addItem(ListItem item) {
  items.add(item);
  handlerManager.fireEvent(new ItemAddedEvent(item));
 }

When fireEvent is called the HandlerManager first calls setSource on the event object and sets it to the value passed into the constructor of the HandlerManager. It will then look for handlers registered against the given event and call them in the order they were registered in.

Registering an EventHandler

At the moment there's no way for a client to listen for the ItemAdded event. In order for this to happen we have to add an addItemAddedHandler to our ListModel class. This looks as follows:

public void addItemAddedHandler(ItemAddedHandler handler) {
      handlerManager.addHandler(ItemAddedEvent.getType(),handler);  
}

The Complete Model

Here's the complete ListModel code:

public class ListModel {
 private final HandlerManager handlerManager = new HandlerManager(this);
 private final List items = new ArrayList<ListItem>();

 public void addItem(ListItem item) {
  items.add(item);
  handlerManager.fireEvent(new ItemAddedEvent(item));
 }
 
 public void removeItem(ListItem item) {
  items.remove(item);
  handlerManager.fireEvent(new ItemRemovedEvent(item));
 }
 
 public void removeAll() {
  for (ListItem item : items) {
   handlerManager.fireEvent(new ItemRemovedEvent(item));  
  }
  
  items.clear();
 }
 
 public List getItems() {
  return Collections.unmodifiableList(items);
 }
 
 public void addItemAddedHandler(ItemAddedHandler handler) {
  handlerManager.addHandler(ItemAddedEvent.getType(),handler);  
 }
 
 public void addItemRemovedHandler(ItemRemovedHandler handler) {
  handlerManager.addHandler(ItemRemovedEvent.getType(),handler);
 }
}

From this you can see we've added events when an item is removed, and also fire the remove event when all the items are cleared. For completeness, the following show the ItemRemovedHandler and ItemEvent classes:

public interface ItemRemovedHandler extends EventHandler {

 void onItemRemoved(ItemRemovedEvent event);
}

public class ItemRemovedEvent extends GwtEvent<ItemRemovedHandler> {
 private static final Type<ItemRemovedHandler> TYPE = new Type<ItemRemovedHandler>();

 private final ListItem listItem;
 
 public ItemRemovedEvent(ListItem listItem) {
  this.listItem = listItem;
 }
 
 public static Type<ItemRemovedHandler> getType() {
  return TYPE;
 }
 
 public ListItem getListItem() {
  return listItem;
 }
 
 @Override
 protected void dispatch(ItemRemovedHandler handler) {
  handler.onItemRemoved(this);
 }

 @Override
 public com.google.gwt.event.shared.GwtEvent.Type<ItemRemovedHandler> getAssociatedType() {
  return TYPE;
 }
}

The List Component

The list component is very much simplified from the previous article, simply being a wrapper around either an LI or OL element:

public class ListComponent extends Widget {
 private static final String IDENTIFIER_PROPERTY = "IDENTIFIER"; 
 
 public enum ListType {
  ORDERED {
   protected Element createElement() {
    return Document.get().createOLElement();
   }
  },  
  UNORDERED {
   protected Element createElement() {
    return Document.get().createULElement();
   }
  };
  
  protected abstract Element createElement();
 }

 
 public ListComponent(ListType type) {
  setElement(type.createElement());
 }
 
 public void addItem(String label, Object identifier) {
  LIElement liElement = Document.get().createLIElement();
  liElement.setInnerText(label);
  liElement.setPropertyObject(IDENTIFIER_PROPERTY, identifier);
  
  getElement().appendChild(liElement);
 }
 
 public void removeItem(Object identifier) {
  Element childNode = getElement().getFirstChildElement();
  
  while (childNode != null) {
   if (identifier.equals(childNode.getPropertyObject(IDENTIFIER_PROPERTY))) {
    childNode.removeFromParent();
    break;
   }
   
   childNode = childNode.getNextSiblingElement();
  }
 }
}

As you can see here, an item consists of a label and an object identifier. The identifier is stored as an Object property in the new LI element so that during remove we can find the given element for a particular indentifier.

Binding the Model to the UI component

With the ListModel finished, we now need something that will register for events and modify a UI component when something is added. For this we'll create a binder which will update a UI list. It looks like this :

public class ListBinder {
 public ListBinder(final ListComponent list, ListModel listModel) {

  listModel.addItemAddedHandler(new ItemAddedHandler() {
   public void onItemAdded(ItemAddedEvent event) {
    ListItem listItem = event.getListItem();
    list.addItem(listItem.getLabel(), listItem);
   }
  });

  listModel.addItemRemovedHandler(new ItemRemovedHandler() {
   public void onItemRemoved(ItemRemovedEvent event) {
    list.removeItem(event.getListItem());
   }
  });
 }
}

The binder is very simple, in that it converts the events triggered by the model into UI actions. It's useful as it keeps a nice seperation of concerns.

A Quick Test

Finally we come to the fun part, actually testing this. For this I created a simple test client that adds a list item every second:

public class TestClient implements EntryPoint {

 public void onModuleLoad() {
  final ListModel model = new ListModel();
  final ListComponent list = new ListComponent(ListType.ORDERED);
  
  ListBinder binder = new ListBinder(list, model);
  
  Timer t = new Timer() {
   private int counter = 0;
   public void run() {
    model.addItem(new ListItem("New Item "+counter++));
   }
  };

  t.scheduleRepeating(1000);
  
  RootPanel.get().add(list);
 }
}

Conclusion

And there we have it, a simple introduction to creating and using a custom GWT 2 event. I could have gone on and extended the ListComponent to fire events when one of the elements are clicked, but that would have distracted from the main aim of this post.

An Eclipse project with all the code for this post can be found here.