During the last few days we have been working on the base layout for our Discovr Administrator App. We have chosen GWT + AppEngine as our implementation platform and while getting things to work we found a few pitfalls implementing a flawless layout using GWT 2.0 and their new UiBinder approach.
On this post we wanted to share some of our experiences and will show you a couple of ways how you can use GWT + UiBinder to implement some basic web layouts.
First thing first
While Google suggests the use of DockLayoutPanel as the starting point for your app layout there are other ways you can follow, coming up next we will walk you thru a couple other options we played with in order to accomplish the following layout:
Disclaimer: before we start we’d like you to know that for this implementation we’ll be using the RootLayoutPanel as our root container but rest assure this is NOT the only widget you can use as the root for your application; a more barebones solution is the use of the Document, for a sample of that you can check Google’s tutorial on the use of UiBinder.
Using DockLayoutPanel to build a basic layout
The DockLayoutPanel is Google’s preferred way to start an app layout, while powerful this solution might not be what you need. A DockLayoutPanel is a panel that places their children docked depending on the position that you indicate and expects your layout to take over the whole window.
Here it is a sample code of what you the UiBinder declaration looks like:
<!DOCTYPE ui:UiBinder SYSTEM "http://dl.google.com/gwt/DTD/xhtml.ent">
<ui:UiBinder
xmlns:ui='urn:ui:com.google.gwt.uibinder'
xmlns:gwt='urn:import:com.google.gwt.user.client.ui'>
<ui:style>
…
</ui:style>
<gwt:DockLayoutPanel unit="EM">
<gwt:north size="5">
<gwt:Label>Header</gwt:Label>
</gwt:north>
<gwt:center>
<gwt:Label>
…
</gwt:Label>
</gwt:center>
<gwt:south size="8">
<gwt:Label>Footer</gwt:Label>
</gwt:south>
</gwt:DockLayoutPanel>
</ui:UiBinder>
… And for your the companion Java Class:
interface Binder extends UiBinder { }
private static final Binder binder = GWT.create(Binder.class);
public void onModuleLoad() {
DockLayoutPanel basicLayout = binder.createAndBindUi(this);
RootLayoutPanel root = RootLayoutPanel.get();
root.add(basicLayout);
}
Going this way will get you somewhere similar to:
Now go ahead and look up for the code that GWT generates behind the scenes:
- The <DockLayoutPanel> is translated to a <div>
- And every child of this widget it’s translated to a <div> also
As you can see the generated code consists of a couple of divs that sets overflow-x and overflow-y in hidden, basically that tell the browser your page will not have vertical scroll nor horizontal scroll and anything that goes beyond this borders should be hidden.
On the other hand, the size that you specify for the center container is set thru the top and bottom’s property. Why is that? When you specify your center child (aka content in our case) GWT sets a top property that it is the sum of whatever is above the child and then a bottom property that defines the size of the south child therefore making your layout to take the whole window. Let’s see it:
So, When should I use this?
You may want to use a DockLayoutPanel when you know that your application will use all of the real state of the Window and the components will flow according to the size of the browser’s window, an example of this will be Google Wave, just keep in mind you will like to use some ScrollPanels inside in case your content grows.
Important to note also is that if you are going to use DockLayoutPanel you will have to use RootLayoutPanel as your root container as this is a pre-condition for this widget.
Source code available: DLPanel
Using a VerticalPanel within a ScrollPanel
This is a simple solution that you could use for your layout if what you want is a more typical webpage layout.
Let’s understand these panels:
- ScrollPanel: it’s a simple panel that adds a scroll in your content. Please be sure to add only one widget inside of it as it extends SimplePanel.
- VerticalPanel: as the ScrollPanel, it’s a simple panel but here you can layout your widgets vertically into a single column.
Here it is a sample code of what your UiBinder should look like:
<!DOCTYPE ui:UiBinder SYSTEM "http://dl.google.com/gwt/DTD/xhtml.ent">
<ui:UiBinder
xmlns:ui='urn:ui:com.google.gwt.uibinder'
xmlns:gwt='urn:import:com.google.gwt.user.client.ui'>
<ui:style>
…
</ui:style>
<gwt:ScrollPanel>
<gwt:VerticalPanel>
<gwt:Label>Header</gwt:Label>
<gwt:Label>
…
</gwt:Label>
<gwt:Label>Footer</gwt:Label>
</gwt:VerticalPanel>
</gwt:ScrollPanel>
</ui:UiBinder>
… And for your the companion Java Class:
interface Binder extends UiBinder { }
private static final Binder binder = GWT.create(Binder.class);
public void onModuleLoad() {
ScrollPanel basicLayout = binder.createAndBindUi(this);
RootLayoutPanel root = RootLayoutPanel.get();
root.add(basicLayout);
}
Finally this is how it will look:
Notice that if you resize your browser or the content grows outside the boundaries of the window you will see scroll bars, letting you access the rest of the content:
As you can see, the footer is not been set to be always visible in the bottom of the page… This is one of the cons of this solution. However, you can take a look here for a solution to it.
Now, let’s take a look at the code that GWT generates:
- The <ScrollPanel> is translated to a <div>
- The <VerticalPanel> is translated to a <table>
- What it is inside the <VerticalPanel> depends on the widget that you use
Update: You can also come to the same result by just using
RootPanel.get().add(new VerticalPanel());
instead of using RootLayoutPanel and removing the ScrollPanel altogether from the UIBinder, but in our case it proved that using it helped us in other caveats of our implementation.
So, when should I use this?
You may want to use this prefixed solution when you know that you content may grow a bit and you need a scroll to display all of it, this is pretty much the normal behavior of a web page.
Source code available: VScrollPanel
Making it your own : HTMLPanel
Last but not least, this solution will need more work than the others but sometimes might come handy.
HTMLPanel is a div based panel where you can add plain HTML markup. While this solution needs a specific position for the elements that you want to show, you have more freedom to build your layout.
A drawback is that there are some useful CSS hacks for compatibility browsers that GWT automatically provides when you use their own panels. If you use plain HTML, is your responsibility to hack the elements that you will put inside the widget to be compatible for all browsers.
So, When should I use this?
When the layout that you are building needs more flexibility to position elements or you already have the layout yourself (useful when integrating with legacy code).
For this solution we are not going to provide source code, since it is a layout based on plain old HTML DOM elements.
Last important points
So here we are with some tips to help you start up the base layout for your app, but before we go we want to give you a couple of extra suggestions to making it right:
- Create a wireframe and discuss pros and cons about the implementation with your mates.
- Think about the panels and try those which you see a fit with the project that you are developing, but remain open to change them, GWT is prompt to surprise you when you never expect it.
- Use UIBinder and GWT’s layout panels whenever possible. Remember if you use plain HTML you will have to position the elements yourself and account for them in all browsers.
- Last but not least, test your layout in all major browsers and don’t forget to try resizing your window randomly and see how your app looks on it, you never know what you will find under these scenarios.
GWT goes a long way removing much of the hard parts when developing web applications but remember this is still web stuff you are dealing with so TEST as much as you can and don’t leave any scenario out… you know Murphy!
Posted by Helga Alvarez
