UiBinder

The generator is attached to one interface. UiBinder<U, O> has a single method, U createAndBindUi(O owner), and two type parameters:

You declare a sub-interface (conventionally a nested Binder), ask the compiler for an implementation with GWT.create, and call createAndBindUi(this) once per instance:

Source: GWT — UiBinder: Hello Widget World

GWT.create(Binder.class) is deferred binding (see Deferred Binding & Generators): the rule in UiBinder.gwt.xml says <generate-with class="com.google.gwt.uibinder.rebind.UiBinderGenerator"> for every type assignable to UiBinder (and a second, identical rule for UiRenderer, covered below). The generator runs while the compiler resolves each binder, so in the compiled JavaScript the call is a plain new of the generated BookCard_BinderImpl class. That class keeps no per-view state (every createAndBindUi call builds its own helper object), so one binder in a static final field is shared by all instances of the owner. Asking for the interface itself, GWT.create(UiBinder.class), fails:

The template is a classpath resource that ends in .ui.xml. By default its name comes from the enclosing class of the binder when the binder is nested (BookCard.Binder reads .../BookCard.ui.xml) and from the binder’s own name when it is a top-level interface (BookBinder reads .../BookBinder.ui.xml), in the same package. The Javadoc of UiBinder states this rule for the owner class (bar.baz.Foo is sought in /bar/baz/Foo.ui.xml); the 2.13.1 UiBinderGenerator source shows the nested-binder rule. In a Maven project put the template under src/main/resources in the same package as the class, which is where the Bookshelf keeps ShellView.ui.xml and BookEditor.ui.xml.

When a missing template is the problem, the message names the exact path that was searched:

Every template has the same skeleton: a root ui:UiBinder element in the namespace urn:ui:com.google.gwt.uibinder, plus one namespace per Java package whose classes the template uses. The prefix is free; ui and g are the convention.

Source: GWT — UiBinder: HTML entities

An attribute name="value" on a widget element becomes a call to setName(value) on the widget; a visibleItemCount="1" is ListBox.setVisibleItemCount(1). Every JavaBean-style setter of the widget can be used, and the generator converts the string to the setter’s parameter type. The parsers registered in AttributeParsers (2.13.1 source) cover the following parameter types:

A value that cannot be parsed is a compile error that names the element:

Two attributes are available on every widget because they come from UIObject: styleName replaces the widget’s own style names (like setStyleName) and addStyleNames adds names without clobbering the built-in ones (like addStyleName). The Developer Guide stresses that addStyleNames is plural.

Source: GWT — UiBinder: Hello Widget World

A widget that implements HasText accepts text as its body (<g:Label>Hello</g:Label>) and a widget that implements HasHTML accepts markup (<g:HTML><ul><li>Sidebar</li></ul></g:HTML>). Other panels do not accept stray text or markup; they accept child widgets. The generator refuses both mistakes with these messages:

When markup is needed inside a widget tree use an HTMLPanel or a HasHTML widget such as <g:HTML>, as the next section explains.

Any panel that implements HasWidgets can hold child widgets in a template. Some panels need special child elements, documented in each widget’s Javadoc. DockLayoutPanel, the root of the Bookshelf shell, gathers its children in north, south, east, west and center elements:

Source: GWT — UiBinder: Using Panels

This is the real ShellView.ui.xml of the Bookshelf client (the layout panel itself is covered on the panels-and-layout page). Elements such as north and center do not represent runtime objects, which is why their names start with a lowercase letter: other special non-object elements follow the same convention (header, item, tab, layer). They cannot carry a ui:field, because there would be nothing to put in the field. With 2.13.1 the compiler does not complain about a stray ui:field on north unless the owner declares a field for it; then you get the usual Template ... has no ui:field attribute for ...Owner#n error. The element names used by each panel are checked too: the DockLayoutPanelParser source (2.13.1) rejects any other child with Child must be one of <g:north>, <g:south>, <g:east>, <g:west> or <g:center>, but found ... and allows only one center (message from the source, not reproduced).

@UiField(provided = true) reverses the direction: the owner creates the object and the template only uses it. The Javadoc says that a provided field "must be filled before createAndBindUi is called". The field therefore has to be assigned before the call, normally from a constructor argument, which makes it the dependency-injection-friendly form:

The matching template declares the same name with ui:with (the declared type must match the field):

The generated code reads the field and checks it with an assert, which is removed from production JavaScript (the compiler flag -checkAssertions is off by default), so a null surfaces later as a NullPointerException in the generated code, and in Development Mode or a GWTTestCase run with assertions enabled with the first message:

Source: GWT — UiBinder: Share resource instances

The RatingStars widget of the Bookshelf has one constructor, RatingStars(int max), annotated @UiConstructor:

Source: GWT — UiBinder: Using a widget that requires constructor args

The attribute is named after the parameter (max) and is required: leaving it out gives <b:RatingStars> missing required attribute(s): max: <b:RatingStars> (:2). The generated code is new RatingStars((int)get_MAX_STARS()): the value was parsed to the parameter’s type. A class may have only one @UiConstructor (the source reports X has more than one constructor annotated with @UiConstructor). Parameter names are read from the source, so the widget’s source must be on the GWT source path (a library that ships only classes needs its sources JAR on the classpath, as for all GWT code).

ShelfBadge(String shelf) is a class the template cannot construct on its own, so the owner provides a factory:

The generated line is final ShelfBadge badge = owner.makeBadge();. The factory’s return type decides which elements it serves: the 2.13.1 source rejects two factories for the same type with Duplicate factory in class BookCard for type ShelfBadge (message from the source, not reproduced). If the factory method has parameters they become required attributes of the element, like a @UiConstructor. The factory is called on the owner, so it can use anything the owner already has; set the owner’s fields before calling createAndBindUi, because the factory runs inside it (the book field above is assigned first for that reason).

Source: GWT — UiBinder: Using a widget that requires constructor args

A field reference is written in braces: {res.logo}, {msg.copies}, {book.getTitle}. The first part is the field name (the field attribute of a resource, or a ui:field of the template); every further part is a method call without arguments, written without parentheses and with the exact method name. This is not JavaBean property syntax. {book.title} calls a method named title(), and since Book has getTitle() the 2.13.1 generator stops with:

For a Messages interface or a CssResource, whose accessors are named after the key (copies(), card()), the shorthand reads naturally ({msg.copies}, {style.card}); for a bean write the getter’s real name ({book.getTitle}). A reference to a field that was not declared reports in {msg.copies}, no field named msg: <g:Label text='{msg.copies}'> (:2) (see the pitfalls table). References also work in plain HTML attributes (class="{style.card}", href="{terms.getSafeUri}") and in text through ui:text and ui:safehtml.

ui:with declares a field of any type, which the generator instantiates with GWT.create(<type>). That makes Messages interfaces, ClientBundle interfaces and any class with a default constructor (or an interface with a deferred-binding rule) available as {msg.save}, {res.style.banner}:

The generated code is msg = (BookMessages) GWT.create(BookMessages.class); and borrow.setText("" + get_msg().save() + "");. Nothing requires the type to implement ClientBundle. When the owner has a @UiField(provided = true) of the same name, the field is taken from the owner instead of being created (the book example above). A type that cannot be found gives No such type com.example.Nope: <ui:with field='x' type='com.example.Nope'> (:2).

A resource that needs constructor arguments takes them from a ui:attributes child, whose attributes are matched to the constructor parameters by name; the constructor must be marked @UiConstructor, and an enum argument is given by its constant name:

The label rendered Save (DARK). Only a single ui:attributes child is allowed (<ui:with> can only contain a single <ui:attributes> child Element.), and the attribute may refer to an earlier resource (msg="{msg}").

Source: GWT — UiBinder: Using an external resource

ui:style writes CSS where it is used. The generator builds a CssResource interface and a ClientBundle for it, so a misspelled class is caught at compile time and the real class names are obfuscated, which gives each template its own CSS namespace.

The class names are obfuscated by default (GF4HBSC above). Setting the configuration property CssResource.style to pretty in the module (<set-configuration-property name="CssResource.style" value="pretty"/>) makes them readable, which is handy while debugging; the probe printed names such as .GCO54G-C-com-example-ub-client-widgets-BookCard_BinderImpl_GenCss_style-card. A misspelled class in a reference is a compile error: Could not find no-arg method named prettty in type com.google.gwt.resources.client.CssResource for {style.prettty} on an untyped block.

Programmatic access (the Developer Guide’s MyFoo.MyStyle example) is the typed @UiField Style style; above: the generator assigns owner.style = style;.

Source: GWT — UiBinder: Hello Stylish World

An external ClientBundle brought in with ui:with is not injected for you. This is the pitfall the compile step does not catch: the class name is applied but the rules are never added to the page unless the owner calls ensureInjected() on the style:

The probe loaded the same page twice and counted the rule Res-Style-banner { color: navy } in the final DOM: 0 occurrences without ensureInjected(), 1 with it (the div had the class in both cases).

Source: GWT — UiBinder: Using an external resource

These two resource elements wrap ClientBundle methods and are listed next to ui:style by the Developer Guide ("the same is true of the other resource elements"), though their attributes are documented only in the generator source (UiBinderParser, 2.13.1):

In the probe the 16 by 16 PNG and the 21-byte text file were small enough to be inlined, so the DOM held a data URI for each:

Source: GWT — UiBinder: Using an external resource

A ui:data or ui:image without its required attribute fails with Missing required attribute "src". The full story of bundling, spriting and inlining belongs to the ClientBundle & Images page.

ui:import makes a static constant of a class available as a field, so a template can read a number or string defined in Java:

Source: GWT — UiBinder: Hello Stylish World

The field is referred to by its last name (MAX_STARS). It must exist and be static (Unable to locate a field named MAX_STARS in ..., Field MAX_STARS in type ... is not static).

ui:text inserts a text value (escaped) from a field; ui:safehtml inserts a SafeHtml value (trusted, produced by the safe-HTML builders) into an HTML context. Both are for values you hold in Java, not for values that can change after construction.

With note provided by the owner as new SafeHtmlBuilder().appendEscaped("a <b>b</b>").toSafeHtml() the page showed <p>Note: a <b>b</b></p>: the value is data, and the escaping happened in the builder. Objects used this way are a "one-way ticket" in the words of the Developer Guide: asString() is called at render time (often at compile time, when the method just returns a constant), so a @UiField to such an object has no handle on the DOM it produced.

Source: GWT — UiBinder: Hello Html Resources

Three attributes on the root element configure the generated interface (they correspond to the arguments of the @Generate annotation of LocalizableResource), and the elements ui:msg, ui:ph and ui:attribute mark what to translate:

Source: GWT — UiBinder i18n: Bonjour, Tout Le Monde

Compile with the -extra directory set (the Maven plugin’s <extra> parameter) and the compiler writes one properties file per template into the extras directory, in a folder named after the module. For the probe (module renamed probe) the file extra/probe/com.example.ub.client.i18n.LoanStatusBinderImplGenMessages.properties contained:

The keys are MD5 hashes of the message content (that is what MD5KeyGenerator selects), so translations survive when messages move inside the template and an identical message used in two templates is translated once. The ui:ph="name" attribute produced the two placeholders nameBegin and nameEnd; the Developer Guide still shows older names (brandedSpanOpen and brandedSpanClose), so read the generated comments rather than guessing. A translator copies the file to a locale file named after the generated messages class, in the template’s package (the package prefix is dropped from the file name), next to the .ui.xml:

With <extend-property name="locale" values="es"/> in the module (two permutations: default and es), opening the page with ?locale=es rendered the same template in Spanish:

The {0}{1} pair in a message stands for the begin and end of the placeholder element: the generator keeps the element in place, and the owner’s code still writes into it (reader.setInnerText("Ada")). All the project’s messages for a locale can also be gathered in one file named LocalizableResource_<locale>.properties in the package com/google/gwt/i18n/client, which works because every generated Messages interface descends from LocalizableResource. The attributes of ui:msg and ui:attribute used to be written with the ui: prefix, as the Developer Guide still does; that spelling still compiles but warns: Deprecated prefix "ui:" on "ui:description". Use "description" instead. (and the same for ui:name). The Developer Guide says the properties land under a folder named after the fully-qualified module, while the 2.13.1 compiler wrote them under extra/probe/, the rename-to name of the probe module.

Source: GWT — UiBinder i18n: Messages with unclobberable portions