GWT UI Binder Use Cases

Ray Ryan

This document provides various use cases for the use of the UiBinder, a proposed service to generate Widget and DOM structures from XML markup.

Background

There are problems with the declarative ui template service as it was originally proposed

• A template-based UI must be instantiated via GWT.create(), causing an implementation detail to be visible as public api
• Within a template, only widgets with a zero arg constructor can be used
• CssResource and other ImmutableResourceBundle variants cannot be used
• Template xml files are found by magical name matching conventions, and applying more than one xml template to a class is impossible

In addressing these issues, we have talked about encouraging a proxy style of use (basically, use Composite to wrap whatever widget gets GWT.create()'d), but dislike the extra object creation implied. We also hope for a system that can choose to use innerHTML, cloning, or DOM assembly as makes sense per browser type. These shortcomings could be addressed by a combination of developer discipline (yuck) and perhaps the builder pattern, but we still found ourselves faced with the likelihood of hurried developers wrapping an unneeded, generated object.

Emily hit upon the idea of the Configurator (here rechristened UiBinder). It’s like a factory, but responsible for filling in the fields of a Widget (or other object) that someone else instantiates, rather than instantiating one itself. This seems to offer all the benefits of a builder, with no concerns of extra object creation, and as a nice side effect avoids a lot of boilerplate. This document illustrates its application in various use cases.

/**
 * Interface implemented by classes that generate DOM or Widget structures from
 * ui.xml template files, and which inject portions of the generated UI into the
 * fields of an owner.
 * <p>
 * The generated UiBinder implementation will be based on an xml file resource
 * in the same package as the owner class, with the same name and a "ui.xml"
 * suffix. For example, a UI owned by class {@code bar.baz.Foo} will be sought
 * in {@code /bar/baz/Foo.ui.xml}. (To use a different template file, put the
 * {@link UiTemplate} annotation on your UiBinder interface declaration to point
 * the code generator at it.)
 *
 * @param <U> The type of the root object of the generated UI, typically a
 *          subclass of {@link com.google.gwt.dom.client.Element} or
 *          {@link com.google.gwt.user.client.ui.UIObject}
 * @param <O> The type of the object that will own the generated UI
 */
public interface UiBinder<U, O> {
  
  /**
   * Creates and returns the root object of the UI. If possible the creation of
   * the rest of the UI is deferred until {@link #bindUi} is called.
   */
  U createUiRoot();

  /**
   * Completes the creation of a UI started with a call to {@link #createUiRoot},
   * and fills any owner fields tagged with {@link UiField}.
   */
  void bindUi(U root, O owner);
  
  /**
   * Convenience method that creates and binds the UI in one call. May be
   * optimized rather than actually calling both {@link #createUiRoot} and
   * {@link #bindUi}.
   */
  U createAndBindUi(O owner);
}

Hello World

Make a simple generated UI, with a named element, and without widgets.

<!-- HelloWorld.ui.xml -->

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'>
  <div>
    Hello, <span ui:field='nameSpan'/>.
  </div>
</ui:UiBinder>

public class HelloWorld extends UIObject { // Could extend Widget instead

  interface MyUiBinder extends UiBinder<DivElement, HelloWorld> {}
  private static MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  @UiField SpanElement nameSpan;

  public HelloWorld(String name) {
    // call to createAndBindUi sets this.nameSpan
    setElement(uiBinder.createAndBindUi(this));
    nameSpan.setInnerText(name);
  }
}

// Use:

SpanElement helloWorld = new HelloWorld("World").getElement();

Hello Composite World

Make a simple widget-based UI

<!-- HelloWidgetWorld.ui.xml -->

<ui:UiBinder 
  xmlns:ui='urn:ui:com.google.gwt.uibinder'
  xmlns:g='urn:import:com.google.gwt.user.client.ui'>
  <g:HTMLPanel>
    Hello, <g:ListBox ui:field='listBox'/>.
  </g:HTMLPanel>
</ui:UiBinder>

public class HelloWidgetWorld extends Composite {

  interface MyUiBinder extends UiBinder<Widget, HelloWidgetWorld> {}
  private static MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  @UiField ListBox listBox;

  public HelloWidgetWorld(String... names) {
    // sets listBox
    initWidget(uiBinder.createAndBindUi(this));
    for (String name : names) { listBox.addItem(name); }
  }
}

// Use:

HelloWidgetWorld helloWorld =
  new HelloWidgetWorld("able", "baker", "charlie");

Hello Deferred World

Note that this example uses the same ui.xml file as the first. Templates need have no knowledge of what kind of binder will use them.

<!-- HelloWorld.ui.xml -->

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'>
  <div>
    Hello, <span ui:field='nameSpan'/>.
  </div>
</ui:UiBinder>

public class Deferral extends Widget {

  interface MyUiBinder extends UiBinder<SpanElement, Topical> {}
  private static MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  @UiField SpanElement nameSpan;

  public Deferral(String name) {
    setElement(uiBinder.createUiRoot());
  }

  @Override protected onAttach() {
    // set nameSpan
    uiBinder.bindUi((SpanElement)getElement(), this);
    nameSpan.setInnerText(name);
    super.onAttach();
  }
}

// Use:

Deferral helloDeferral = new Deferral("World");

Putting a label on a checkbox (referring to generated ids within a template)

You want to make your personal variant on the single most common widget, a checkbox with a nice, accessible HTML label element tied to it:

<!-- LabeledCheckBox.ui.xml -->

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'>
  <span>
    <input type='checkbox' ui:field='myCheckBox'>
    <label ui:for='myCheckBox' ui:field='myLabel'/>
  </span>
</ui>

public class LabeledCheckBox extends Widget {
  interface MyUiBinder extends UiBinder<Widget, LabeledCheckbox> {}
  private static MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  @UiField InputElement myCheckBox;
  @UiField LabelElement myLabel;

  public LabeledCheckBox() { setElement(uiBinder.createAndBindUi(this)); }
 
  public void setValue(boolean b) { myCheckBox.setChecked(b); }

  public boolean getValue() { return myCheckBox.isChecked(); }

  public void setName(String name) { myLabel.setInnerText(name); }

  public String getName() { return myLabel.getInnerText(); }
}

The proposal here is that a ui: prefix on any attribute other than id fills it with the id generated for a corresponding ui:field.

There are type matching issues here. The ui:field of a DOM element is a string id, while that for a UIObject is typed. So, this should fail with a type mismatch:

<some:WidgetOfSomeKind ui:field='theWidget'> <label g:for='theWidget' />

The use of attribute prefixing for this would be a mistake, a bad use of XML. In particular, it fights the use of XML tools to enforce things like, "all labels must have a 'for' attribute."

Instead, we should bite the bullet and adopt a mini-expression language, something like:

<ui:UiBinder
  xmlns:ui='urn:ui:com.google.gwt.uibinder'>
  <span>
    <input type='checkbox' ui:field='myCheckBox'>
    <label for='{myCheckBox}' ui:field='myLabel'/>
  </span>
</ui:UiBinder>

Using an ImmutableResourceBundle (e.g. CssResource) with a UiBinder

<!-- LogoNamePanel.ui.xml -->
<ui:UiBinder
  xmlns:ui='urn:ui:com.google.gwt.uibinder'
  xmlns:g='urn:import:com.google.gwt.user.client.ui'
  xmlns:res='urn:with:com.my.app.widgets.logoname.Resources'>
  <g:HTMLPanel>

    <img res:apply='logoImage'>

    <div res:class='style.mainBlock'>
      <div res:apply='style.userPictureSprite'>
        Well hello there
        <span res:class='style.nameSpan' ui:field='userNameField'/>
      </div>
    </div>
  </g:HTMLPanel>
</ui:UiBinder>

public class LogoNamePanel extends Composite {
  interface MyUiBinder extend UiBinder<Widget, LogoNamePanel> {}
  private static MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  @UiField SpanElement nameSpan;

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

  public void setUserName(String userName) {
    nameSpan.setInnerText(userName);
  }
}

public interface Resources extends ClientBundle {
  @Resource("Style.css")
  Style style();

  @Resource("Logo.jpg")
  ImageResource widgetyImage();

  public interface Style extends CssResource {
    String mainBlock();
    String nameSpan();
    Sprite userPictureSprite();
  }
}

The with: uri type marks an object whose methods can be called to fill in attribute values. If no public api is provided to set the "with" argument (as in this example), it must be instantiable by GWT.create().

An element can be passed as an argument to a method on such resource class via an apply attribute, as illustrated above with the Sprite and ImageResource uses.

Note that there is no requirement that a with: class implement the ClientBundle interface.

As above, this is an abuse of attribute prefixing, and a bad idea. Here again we should use our little expression language:

<ui:UiBinder
  xmlns:ui='urn:ui:com.google.gwt.uibinder'
  xmlns:g='urn:importcom.google.gwt.user.client.ui'
  xmlns:res='urn:with:com.my.app.widgets.logoname.Resources'>

  <g:HTMLPanel>

    <div class='{res.style.mainBlock}'>
      Well hello there
      <span class='{res.style.nameSpan}' ui:field='userNameField'/>
    </div>
  </g:HTMLPanel>
</ui:UiBinder>

Share ImmutableResourceBundle instances

Extends LogoNamePanel (from the example above) to allow its bundle to be passed in.

public class LogoNamePanel extends Composite {
  interface MyUiBinder extend UiBinder<Widget, LogoNamePanel> {}
  private static MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  @UiField SpanElement nameSpan;
  final Resources resources;

  public LogoNamePanel(Resources resources) {
    initWidget(uiBinder.createAndBindUi(this));
    this.resources = resources;
  }

  public void setUserName(String userName) {
    nameSpan.setInnerText(userName);
  }

  @UiFactory
  public Resources getResources() {
    return resources;
  }
}

This can be even more concise:

public class LogoNamePanel extends Composite {
  interface MyUiBinder extend UiBinder<Widget, LogoNamePanel> {}
  private static MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  @UiField SpanElement nameSpan;
  @UiField(provided = true)
  final Resources resources;

  public LogoNamePanel(Resources resources) {
    initWidget(uiBinder.createAndBindUi(this));
    this.resources = resources;
  }

  public void setUserName(String userName) {
    nameSpan.setInnerText(userName);
  }
}

Using a widget that requires constructor args

You have an existing widget that needs constructor arguments.

public CricketScores(String... teamNames) {...} 

You use it in a template.

<!-- UserDashboard.ui.xml -->
< ui:UiBinder
  xmlns:ui='urn:ui:com.google.gwt.uibinder'
  xmlns:g='urn:import:com.google.gwt.user.client.ui'
  xmlns:my='urn:import:com.my.app.widgets' >

  <g:HTMLPanel>
    <my:WeatherReport ui:field='weather'/>
    <my:Stocks ui:field='stocks'/>
    <my:CricketScores ui:field='scores' />
  </g:HTMLPanel>
</ui:UiBinder>

public class UserDashboard extends Composite {
  interface MyUiBinder extends UiBinder<Widget, UserDashboard> {}
  private static MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

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

An error results:

UserDashboard.ui.xml:7:2 [ERROR] com.my.app.widgets.CricketScores
has no default (zero args) constructor. You can define a
@UiFactory annotated method on UserDashboard to create an instance;
mark a CrickectScores field of UserDashboard with @UiField(provided=true)
and put an instance there; or annotate a constructor of CricketScores with 
@UiConstructor to allow its arguments to be provided by the template.

So you either make the @UiFactory method:

public class UserDashboard extends Composite {
  interface MyUiBinder extends UiBinder<Widget, UserDashboard>;
  private static final MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  private final String[] teamNames;

  public UserDashboard(String... teamNames) {
    this.teamNames = teamNames;
    initWidget(uiBinder.createAndBindUi(this));
  }

  /** Used by MyUiBinder to instantiate CricketScores */
  @UiFactory CricketScores makeCricketScores() { // method name is insignificant
    return new CricketScores(teamNames);
  }
}

or perhaps:

public class UserDashboard extends Composite {
  interface MyUiBinder extends UiBinder<Widget, UserDashboard>;
  private static final MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  public UserDashboard() {
    this.teamNames = teamNames;
    initWidget(uiBinder.createAndBindUi(this));
  }

  /** 
   * Used by MyUiBinder to instantiate CricketScores. 
   * Arguments to be filled in the template
   */
  @UiFactory CricketScores(String... teamNames) {
    return new CricketScores(teamNames);
  }
}

<!-- UserDashboard.ui.xml -->
<g:HTMLPanel xmlns:ui='urn:ui:com.google.gwt.uibinder'
  xmlns:g='urn:import:com.google.gwt.user.client.ui'
  xmlns:my='urn:import:com.my.app.widgets' >

  <my:WeatherReport ui:field='weather'/>
  <my:Stocks ui:field='stocks'/>
  <my:CricketScores ui:field='scores' teamNames='AUS, SAF, WA, QLD, VIC'/>
</g:HTMLPanel>

or annotate the constructor:

public @UiConstructor CricketScores(String... teamNames) {...} 

<!-- UserDashboard.ui.xml -->
<g:HTMLPanel xmlns:ui='urn:ui:com.google.gwt.uibinder'
  xmlns:g='urn:import:com.google.gwt.user.client.ui'
  xmlns:my='urn:import:com.my.app.widgets' >

  <my:WeatherReport ui:field='weather'/>
  <my:Stocks ui:field='stocks'/>
  <my:CricketScores ui:field='scores' teamNames='AUS, SAF, WA, QLD, VIC'/>
</g:HTMLPanel>

or fill in a field marked with @UiField(provided=true):

public class UserDashboard extends Composite {
  interface MyUiBinder extends UiBinder<Widget, UserDashboard>;
  private static final MyUiBinder uiBinder = GWT.create(MyUiBinder.class);

  @UiField(provided=true)
  final CricketScores cricketScores; // cannot be private

  public UserDashboard(CricketScores cricketScores) {
    // DI fans take note!
    this.cricketScores = cricketScores;
    initWidget(uiBinder.createAndBindUi(this));
  }
}

Apply different xml templates to the same widget

You're an MVC developer. You have a nice view interface, and a templated Widget that implements it. How might you use several different xml templates for the same view?

public class FooPickerController {
  public interface Display {
    HasText getTitleField();
    SourcesChangeEvents getPickerSelect();
  }

  public void setDisplay(FooPickerDisplay display) { ... }
}

public class FooPickerDisplay extends Composite
    implements FooPickerController.Display {
 
  @UiTemplate("RedFooPicker.ui.xml")
  interface RedBinder extends UiBinder<Widget, FooPickerDisplay> {}
  private static RedBinder redBinder = GWT.create(MyUiBinder.class);

  @UiTemplate("BlueFooPicker.ui.xml")
  interface BlueBinder extends UiBinder<Widget, FooPickerDisplay> {}
  private static BlueBinder blueBinder = GWT.create(MyUiBinder.class);

  @UiField HasText titleField;
  @UiField SourcesChangeEvents pickerSelect;

  public HasText getTitleField() {
    return titleField;
  }
  public SourcesChangeEvents getPickerSelect() {
    return pickerSelect;
  }

  protected FooPickerDisplay(UiBinder<Widget, FooPickerDisplay> binder) {
    initWidget(uiBinder.createAndBindUi(this));
  }

  public static FooPickerDisplay createRedPicker() {
    return new FooPickerDisplay(redBinder);
  }

  public static FooPickerDisplay createBluePicker() {
    return new FooPickerDisplay(blueBinder);
  }
}