blob: d16bb54c766627ba990ae6a650344304b868cfcf [file] [log] [blame]
Copyright 2008 Google Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you
may not use this file except in compliance with the License. You may
may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
implied. License for the specific language governing permissions and
limitations under the License.
<!DOCTYPE ui:UiBinder
<!ENTITY % MyEntities SYSTEM "MyEntities.ent">
This scary DOCTYPE section is not required. It's here to demonstrate two
First, this bit:
allows you to use familiar HTML entities like %nbsp; and &bull;,
which are not part of XML.
Next, the bit in square brackets pulls in additional definitions for
&point-left; and &point-right; from local file MyEntities.ent.
You don't have to be so verbose to include a local file! For
example, you might instead grab your own copy of xhtml.ent
and add your custom entity definitions to it, and use this
for your DOCTYPE:
<!DOCTYPE ui:UiBinder SYSTEM "my-xhtml.ent">
<ui:UiBinder xmlns:ui=''
<ui:with field='external' type=''>
(This text is ignored, but it's a handy place to document a resource.)
external is used to test receiving a resource from the owner via
@UiField(provided = true), particularly useful for dependency
injection via Gin and the like
<ui:with field='values' type=''>
Tests the default creation of a resource via GWT.create(), and also the ability
for a resource to provide arbitrary objects to arbitrary attributes (look for FooLabel)
Tests creating a CssResource from an external file.
<ui:style field='myStyle' src='WidgetBasedUi.css'
<ui:style field='myOtherStyle' type=''>
/* because we extend WidgetBasedUi.Style and it's tagged @Shared, we can refine the menubar
style defined in other files */
.menuBar.psychedelic {
background-color: Yellow;
/* Visible only to this template */
.privateColor {
color: Purple;
<ui:style field='myTotallyPrivateStyle'>
/* An inline style tied to no public type */
.superPrivateColor {
background-color: Gold;
<gwt:DockPanel ui:field="root" width="100%">
<gwt:Dock direction='NORTH'>
<div style='border: 4px solid gray; padding: 4px; margin: 4px;'>
<img src='' alt="logo" />
<span ui:field="trimmedMessage"><ui:msg description='"title" of the doc'
meaning='would not normally do a "meaning" here'
key='and I would never use "key" at all'>
<!-- A test expects this *not* to be on one line -->
Title area, specified largely in HTML.
<gwt:Dock direction='WEST'>
<div ui:field="sideBar"
style='border: 4px solid gray; padding: 4px; margin: 4px;'
>This could<br/>
be a<br/>
side bar<br/>
or something<br/>
like that...</div>
<gwt:Dock direction='CENTER'>
<p><ui:msg>This is a demonstration and test bed of GWT's shiny UiBinder
package. At the moment it works mainly as described in
<a href=""
this blog post</a>, but it is en route to the use cases desribed at
<a href="http://go/gwt-uibinder" ui:ph="newBlogLink">http://go/gwt-uibinder</a> and
<a href="http://go/gwt-uibinder-i18n" ui:ph="i18nBlogLink">http://go/gwt-uibinder-i18n</a>. Early
adopters should recognize themselves as such, and be prepared to have the
api rug yanked out from under them.</ui:msg></p>
<p ui:field="main">
&point-right;&nbsp;<span ui:field="messageInMain"><ui:msg>This is the main area. It's an <b>HTMLPanel</b>, which allows you to mix
&point-right; &bull; XHTML &bull; &point-left; and regular GWT widgets, more or less with
impunity. Take the following button for example.</ui:msg></span>&nbsp;&point-left;
<gwt:Button ui:field='myButton'>
Button with <b id='shouldSayHTML'>HTML</b> contents...
It's specified using the Button widget, so that it's easy to work with from
Java code. Its markup has a ui:field value of 'myButton', which allows you to get it using the
<i ui:field="nonStandardElement">getMyButton()</i> method from </p>
Here is a similarly clickable
<demo:ClickyLink text="hyperlink based on a custom widget"
ui:field="customLinkWidget" popupText="That tickles! "/>.
<ui:msg description="">
Of course, it could just as easily be a Tree under a MenuBar...
<div class="{myStyle.menuBar}">
<gwt:MenuBar ui:field="topMenuBar" vertical="false">
<div id="higgledy">
<ui:msg description="Last 7 Day Period">
<gwt:MenuBar vertical="true" styleName="{myStyle.menuBar}">
<div id="piggledy">
<ui:msg description="Last 7 Day Period">
<gwt:MenuBar vertical="true" styleName="{myStyle.menuBar} {myOtherStyle.psychedelic}">
<div id="pop-can-has-submenu">
<ui:msg description="Last 7 Day Period">Pop</ui:msg>
<gwt:MenuBar vertical="true" ui:field="dropdownMenuBar"
<gwt:MenuItem ui:field='menuItemCustomDateRange'>
<ui:msg description="Custom date range">
the Dog
<ui:msg>has eaten</ui:msg>
<gwt:MenuItem ui:field="menuItemMop" styleName="moppy">
<ui:msg>the Mop</ui:msg>
<gwt:MenuItem ui:field='menuItemLegacy'>
<span style="white-space:nowrap">The <gwt:MenuItemHTML>pig's in</gwt:MenuItemHTML> a hurry</span>
<gwt:Tree ui:field='myTree' width="100px" />
<gwt:TextBox maxLength="21">21 chars only, please</gwt:TextBox>
<p>...or perhaps a handful of RadioButtons:</p>
<gwt:RadioButton ui:field='myRadioAble' name="radios" text="Able" checked="true">
<ui:attribute name="text" description="radio button name"/>
<gwt:RadioButton ui:field='myRadioBaker' name="radios" text="Baker">
<ui:attribute name="text" description="radio button name"/>
<demo:PointlessRadioButtonSubclass ui:field='emptyRadio' name="radios"
text="Charlie (this one is a subclass of RadioButton)">
<ui:attribute name="text" description="radio button name"/>
<p> ... a StackPanel ... </p>
<gwt:StackPanel stylePrimaryName="myStyle" width="280px" ui:field='myStackPanel'>
<gwt:Label text="Stack One Text" gwt:StackPanel-text="Stack One"
<!-- ui:attribute name="gwt:StackPanel-text" description="Label for Stack One"/
<ui:attribute name="text" description="Content for Stack One Text"/>
<gwt:HTMLPanel gwt:StackPanel-text="Stack Two">
<!-- ui:attribute name="gwt:StackPanel-text" description="Label for Stack Two"/
<ui:msg description="Describe div content">Some other content</ui:msg>
<gwt:Label text="Stack Three Text" gwt:StackPanel-text="Stack Three" />
<p> ... a DisclosurePanel with a text header ... </p>
<gwt:DisclosurePanel text="I just have a text header" ui:field='myDisclosurePanel'>
<!--ui:attribute name="text" description="Label for Disclosure One"/ -->
<gwt:Label text="Disclosure Text" ui:field='myDisclosurePanelItem'>
<ui:attribute name="text" description="Content for Disclosure One Text"/>
<p> ... a DisclosurePanel with a widget header ... </p>
<gwt:Label text="Disclosure Header - closed" gwt:DisclosurePanel-header="true">
<ui:attribute name="text" description="Content for Disclosure Two Text"/>
<gwt:Label text="Disclosure Two - closed">
<ui:attribute name="text" description="Content for Disclosure Two"/>
<p> ... an open DisclosurePanel with a widget header ... </p>
<gwt:DisclosurePanel initiallyOpen="true">
<gwt:Label text="Disclosure Header - open" gwt:DisclosurePanel-header="true">
<ui:attribute name="text" description="Content for Disclosure Two Text"/>
<gwt:Label text="Disclosure Two - open">
<ui:attribute name="text" description="Content for Disclosure Two"/>
<p> ... a DisclosurePanel with no header ... </p>
<gwt:DisclosurePanel initiallyOpen="true">
<gwt:Label text="Disclosure Three">
<ui:attribute name="text" description="Content for Disclosure Three"/>
<p> ... an open DisclosurePanel with a text label and no animation</p>
<gwt:DisclosurePanel text="Disclosure Three - open" initiallyOpen="true"
<gwt:Label text="Disclosure Three">
<ui:attribute name="text" description="Content for Disclosure Three"/>
<p> ... a DisclosurePanel with no content ... </p>
<gwt:DisclosurePanel text="I just have a text header" />
Templates work with ClientBundle. For example,
this label gets its text from somplace tricky and its style from a ClientBundle
defined outside of this UI:</p>
<gwt:Label ui:field='bundledLabel' text="{values.helloText}" styleName="{}"/>
<!-- Note use of id rather than ui:field, to test that ids work on dom elements -->
<p class="{}" id='prettyPara'>
This stylish paragraph also gets its good looks from the
external ClientBundle.
<p ui:field='privateStyleParagraph' class='{myStyle.privateColor}'>
This one is has a private style, defined out in WidgetBaseUi.css and used only by this ui.xml file.
<p ui:field='reallyPrivateStyleParagraph' class='{myOtherStyle.privateColor}'>
And this style is defined right here inside the ui.xml file.
<span ui:field='totallyPrivateStyleSpan' class='{myTotallyPrivateStyle.superPrivateColor}'>
(This one too, but even more so.)
Things change. This label uses the new ui:field attribute to declare
its identity. Soon everything
will work that way:
<gwt:Label ui:field='gwtFieldLabel'>Tommy can you hear me? Can you field me near you?</gwt:Label>
<h2>Localization and character escaping</h2>
<p ui:field="funnyCharsParagraph">Templates can be marked up for <b>localization</b>,
which presents alls kinds of exciting opportunities for bugs related to
character escaping. Consider these funny characters " &quot; ' &#39; &amp; &lt; &gt; > { },
and the various places they might make your life miserable, like this
untranslated paragraph.</p>
<p ui:field="funnyCharsMessageParagraph"><ui:msg>They might show up
in body text that has been <b>marked for translation</b>: funny characters " &quot; ' &#39; &amp; &lt; &gt; > { }</ui:msg></p>
<p><ui:msg>Or perhaps in a subelement with a ui:field: <span ui:field='funnyCharsMessageChildSpan'>funny characters " &quot; ' &#39; &amp; &lt; &gt; > { }</span></ui:msg></p>
<p ui:field="funnyCharsProtectedMessageParagraph"><ui:msg>Don't forget about protected untranslatable blocks: <ui:ph name='francine'>funny characters " &quot; ' &#39; &amp; &lt; &gt; > { }</ui:ph></ui:msg></p>
<p ui:field="funnyCharsMessageDomAttributeParagraph" title="funny characters &quot; ' &#39; &amp; &lt; &gt; > { }">
<ui:attribute name="title"/>
Attributes of dom elements can be translated too, like the
tooltip of this paragraph, which features the challenging characters.
<p ui:field="funnyCharsDomAttributeParagraph"
title="funny characters &quot; ' &#39; &amp; &lt; &gt; > { }">
They might also appear in an unstranslated attribute of a dom element, like
the tooltip for this paragraph.
<p>And all the cases above apply to widgets as well:</p>
<gwt:Label>I am an untranslatable HasText with funny characters " &quot; ' &#39; &amp; &lt; &gt; > { }</gwt:Label>
<gwt:HTML>I am an untranslatable HasHTML with funny characters " &quot; ' &#39; &amp; &lt; &gt; > { }</gwt:HTML>
<gwt:Label><ui:msg>I am a translatable <ui:ph name="widgetType" example="myWidget">HasText</ui:ph> with funny characters " &quot; ' &#39; &amp; &lt; &gt; > { }</ui:msg></gwt:Label>
<gwt:HTML><ui:msg>I am a translatable <ui:ph name="widgetType" example="myWidget">HasHTML</ui:ph> with funny characters " &quot; ' &#39; &amp; &lt; &gt; > { }</ui:msg></gwt:HTML>
<demo:ClickyLink ui:field="funnyCharsAttributeWidget"
popupText="funny characters &quot; ' &#39; &amp; &lt; &gt; > { }">
Click to see my untranslatable text passed by attribute
<demo:ClickyLink ui:field="funnyCharsMessageAttributeWidget"
popupText="funny characters &quot; ' &#39; &amp; &lt; &gt; > { }">
<ui:attribute name="popupText"/>
Click to see my translatable text passed by attribute
<h2>Placeholders in localizables</h2>
<p><ui:msg>When you mark up your text for translation, there will be bits
that you don't want the translators to mess with. You can protect
these with <span id="placeholdersSpan" style="font-weight:bold" class="{}"
ui:ph="boldSpan">placeholders</span><ui:ph name="tm"><sup ui:field="tmElement"
<p><ui:msg>You may also need to have <span ui:field="spanInMsg"
style="font-weight:bold" class="{}">named
portions</span> of <span class="{}">translatable text</span></ui:msg></p>
<p><ui:msg>Of course you'll want to be able to do this kind of thing
with widgets <demo:MyDatePicker/> as well, whether they <gwt:Label>HasText<ui:ph name="tm">*TM*</ui:ph></gwt:Label>
or <gwt:HTML>HasHTML<ui:ph name="TM2"><sup ui:field="tmElementJr"
<h2>Any Widget You Like</h2>
<p><demo:AnnotatedStrictLabel text="This widget is not default instantiable." ui:field="strictLabel"/></p>
<p><demo:AnnotatedStrictLabel text="Another constructor based widget, translated this time." ui:field="translatedStrictLabel">
<ui:attribute name="text" description="Arbitrary text"/>
<p><demo:StrictLabel text="More of the same." ui:field="veryStrictLabel"/></p>
<p><demo:StrictLabel text="Likewise, again translated this time." ui:field="translatedVeryStrictLabel">
<ui:attribute name="text" description="Arbitrary text"/>
<p><demo:NeedlesslyAnnotatedLabel ui:field="needlessLabel"
text="Sometimes people do things they don't need to do. Don't punish them."/></p>
<demo:FooLabel ui:field='theFoo' pojo="{values.pojo}"/>
<h2>How to use the debugId, addStyleNames, addDependentStyleNames attributes</h2>
<p>You can use the <strong>debugId</strong>, <strong>addStyleNames</strong>, and <strong>addDependentStyleNames</strong>
attributes on any widget that extends UIObject.
<li><b>debugId</b> will set an <em>id</em> on the element prefixed with <em>gwt-debug</em></li>
<li><b>addStyleNames</b> (comma separated) will add all class names to the existing style (space separated)</li>
<li><b>addDependentStyleNames</b> (comma separated) will concatenate all class names to the existing style with a "-" as a separator</li>
You can/should use FireBug or a simple view source to see the attributes that were created.
<br />
<pre style="border: 1px dashed #666; padding: 5px 0;">
&lt;gwt:Label ui:field="lblDebugId" debugId="joe" addStyleNames="newStyle, anotherStyle" addStyleDependentNames="dependentStyle, anotherDependentStyle" text="a label with debug id" /&gt;
&lt;!-- A button that only adds a single style name, no comma's needed --&gt;
&lt;gwt:Button ui:field="btnGo" debugId="myButton" addStyleNames="buttonStyle" text="a button with extra attributes" /&gt;
<pre style="border: 1px dashed #666; padding: 5px 0;">
&lt;div id="gwt-debug-joe" class="gwt-Label newStyle anotherStyle gwt-Label-dependentStyle gwt-Label-anotherDependentStyle"&gt;A label with a debug id&lt;/div&gt;
&lt;button id="gwt-debug-myButton" class="gwt-Button buttonStyle" tabindex="0" type="button"&gt;Go&lt;/button&gt;</pre>
<gwt:Label ui:field="lblDebugId" debugId="joe" addStyleNames="newStyle, anotherStyle" addStyleDependentNames="dependentStyle, anotherDependentStyle">
A label with a debug id
<gwt:Button ui:field="btnGo" debugId="myButton" addStyleNames="buttonStyle">Go</gwt:Button>
<h2>How to tie handlers automatically!!</h2>
<p>You can add event handlers to template widgets as long as they have
valid ui:field attributes. If the template is shared, each widget can
register listeners for the events it's interested in. In the example
below, we listen to MouseOver events on the status label and clicks
on the button.</p>
<demo:HandlerDemo />
<pre style="border: 1px dashed #666; padding: 5px 0;">
&lt;gwt:Label ui:field="label" text="Looking for happiness?" /&gt;
&lt;gwt:Button ui:field="button" text="Click here to happiness!!" /&gt;
&lt;gwt:TextBox ui:field="textbox" /&gt;
<b>The code:</b>
<pre style="border: 1px dashed #666; padding: 5px 0;">
public class HandlerDemo extends Composite {
interface MyUiBinder extends UiBinder&lt;FlowPanel, HandlerDemo&gt; {}
private static final MyUiBinder binder = GWT.create(MyUiBinder.class);
@UiField Label label;
// No need of declare button here via @UiField if it is not really used
// in the class. Just don't forget to "ui:field" it in the template.
private int counter;
public HandlerDemo() {
@UiHandler({"label", "button"})
protected void doClick(ClickEvent event) {
Window.alert("Yes, now I'm happy!");
counter = 0;
label.setText("Don't mouse over, click me!!!");
protected void doMouseOver(MouseOverEvent event) {
label.setText(counter + ". Don't mouse over, click me!");
protected void doChangeValue(ValueChangeEvent&lt;String&gt; event) {
label.setText("Typing = " + event.getValue());
<h2>People write the darndest markup</h2>
<table border="1" bcolor="yellow" cellpadding="3" ui:field="widgetCrazyTable">
<demo:ExplicitElementPanel tag="thead">
<demo:ExplicitElementWidget tag="td">They have been known</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="td">to write widgets</demo:ExplicitElementWidget>
<demo:ExplicitElementPanel tag="tr">
<demo:ExplicitElementWidget tag="td">that masquerade</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="td">as table cells,</demo:ExplicitElementWidget>
<demo:ExplicitElementPanel tag="tfoot">
<demo:ExplicitElementWidget tag="td">just like these.</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="td">Burma Shave</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="li">You</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="li">can</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="li">imagine</demo:ExplicitElementWidget>
<ol ui:field="widgetCrazyOrderedList">
<demo:ExplicitElementWidget tag="li">similar</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="li">things</demo:ExplicitElementWidget>
<dl ui:field="widgetCrazyDefinitionList">
<demo:ExplicitElementWidget tag="dt">Being</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="dd">done</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="dd">with</demo:ExplicitElementWidget>
<demo:ExplicitElementWidget tag="dd">lists</demo:ExplicitElementWidget>
<gwt:HTMLPanel tag="table" ui:field="customTagHtmlPanel">
<tr><td>Even HTMLPanel gets in on the game</td></tr>
<tr><td>Lately, anyway.</td></tr>