This document explains how to build Widget and DOM structures from XML markup using UiBinder, introduced with GWT 2.0. It does not cover binder's localization features—read about them in Internationalization - UiBinder.


(In this example U is DivElement and O is HelloWorld.)

Any object declared in the ui.xml file, including any DOM elements, can be made available to the owning Java class through its field name. Here, a <span> element in the markup is given a ui:field attribute set to nameSpan. In the Java code, a field with the same name is marked with the @UiField annotation. When uiBinder.createAndBindUi(this) is run, the field is filled with the appropriate instance of SpanElement.

Any panel (in theory, anything that implements the HasWidgets interface) can be used in a template file, and can have other panels inside of it.

Some stock GWT widgets require special markup, which you‘ll find described in their javadoc. Here’s how DockLayoutPanel works:

The DockLayoutPanel‘s children are gathered in organizational elements like <g:north> and <g:center>. Unlike almost everything else that appears in the template, they do not represent runtime objects. You can’t give them ui:field attributes, because there would be nothing to put in the field in your Java class. This is why their names are not capitalized, to give you a clue that they‘re not “real”. You’ll find that other special non-runtime elements follow the same convention.

Another thing to notice is that we can‘t put HTML directly in most panels, but only in widgets that know what to do with HTML, specifically, HTMLPanel, and widgets that implement the HasHTML interface (such as the sidebar under <g:west>). Future releases of GWT will probably drop this restriction, but in the meantime it’s up to you to place your HTML into HTML-savvy widgets.

One of UiBinder's goals is to reduce the tedium of building user interfaces in Java code, and few things in Java require more mind-numbing boilerplate than event handlers. How many times have you written something like this?

In a UiBinder owner class, you can use the @UiHandler annotation to have all of that anonymous class nonsense written for you.

However, there is one limitation (at least for now): you can only use @UiHandler with events thrown by widget objects, not DOM elements. That is, <g:Button>, not <button>.

Every widget that is declared in a template is created by a call to GWT.create(). In most cases this means that they must be default instantiable; that is, they must provide a zero-argument constructor. However, there are a few ways to get around that. In addition to the @UiFactory and @UiField(provided = true) mechanisms described under Shared resource instances, you can mark your own widgets with the @UiConstructor annotation.

An error results:

So you either make the @UiFactory method...

...annotate a constructor...

Finally, you don't have to have your CSS inside your ui.xml file. Most real world projects will probably keep their CSS in a separate file. In the example given below, the src values are relative to the location of the ui.xml file.

And you can set style on a widget, not just HTML. Use the styleName attribute to override whatever CSS styling the widget defaults to (just like calling setStyleName() in code). Or, to add class names without clobbering the widget's baked in style settings, use the special addStyleNames attribute:

Note that addStyleNames is plural.