- 10.1. Get started
- 10.2. Use Errai UI Composite components
- 10.3. Create a @Templated Composite component
- 10.4. Create an HTML template
- 10.5. Use other Widgets in a composite component
- 10.6. How HTML templates are merged with Components
- 10.7. Event handlers
- 10.8. Data Binding
- 10.9. Nest Composite components
- 10.10. Extend Composite components
|
One of the primary complaints of GWT to date has been that it is difficult to use "pure HTML" when building and skinning widgets. Inevitably one must turn to Java-based configuration in order to finish the job. Errai, however, strives to remove the need for Java styling. HTML template files are placed in the project source tree, and referenced from custom "Composite components" (Errai UI Widgets) in Java. Since Errai UI depends on Errai IOC and Errai CDI, dependency injection is supported in all custom components. Errai UI provides rapid prototyping and HTML5 templating for GWT. |
The Errai UI module is directly integrated with Chapter 9, Data Binding and Errai JPA but can also be used as a standalone project in any GWT client application by simply inheriting the Errai UI GWT module, and ensuring that you have properly using Errai CDI's @Inject to instantiate your widgets:
<inherits name="org.jboss.errai.ui.UI" />
If you work better by playing with a finished product, you can see a simple client-server project implemented using Errai UI here .
Before explaining how to create Errai UI components, it should be noted that these components behave no differently from any other GWT Widget once built. The primary difference is in A) their construction, and B) their instantiation. As with most other features of Errai, dependency injection with CDI is the programming model of choice, so when interacting with components defined using Errai UI, you should always
@Inject
references to your Composite components.
@EntryPoint
public class Application {
@Inject
private ColorComponent comp;
@PostConstruct
public void init() {
comp.setColor("blue");
RootPanel.get().add(comp);
}
}
@EntryPoint
public class Application {
private String[] colors = new String[]{"Blue", "Yellow", "Red"};
@Inject
private Instance<ColorComponent> instance;
@PostConstruct
public void init() {
for(String color: colors) {
ColorComponent comp = instance.get();
comp.setColor(c);
RootPanel.get().add();
}
}
}
Custom components in Errai UI are single classes extending from
com.google.gwt.user.client.ui.Composite
, and must be annotated with @Templated.
@Templated
public class LoginForm extends Composite {
/* looks for LoginForm.html in LoginForm's package */
}
With default values, @Templated informs Errai UI to look in the current package for a parallel
".html"
template next to the Composite component Class; however, the template name may be overridden by passing a String into the @Templated annotation, like so:
@Templated("my-template.html")
public class LoginForm extends Composite {
/* looks for my-template.html in LoginForm's package */
}
Fully qualified template paths are also supported, but must begin with a leading '/':
@Templated("/org/example/my-template.html")
public class LoginForm extends Composite {
/* looks for my-template.html in package org.example */
}
Templates in Errai UI may be designed either as an HTML snippit, or as a full HTML document. You may even take an existing HTML page and use it as a template. With either approach, the
"data-field"
annotation is used to identify fragments (by name) in the template, which are used in the Composite component to add behavior, and use additional components to add functionality to the template. There is no limit to how many component classes may share a given HTML template.
We will begin by creating a simple HTML login form to accompany our
@Templated LoginForm
composite component.
<form>
<legend>Log in to your account</legend>
<label for="username">Username</label>
<input id="username" type="text" placeholder="Username">
<label for="password">Password</label>
<input id="password" type="password" placeholder="Password">
<button>Log in</button>
<button>Cancel</button>
</form>
Or as a full HTML document which may be more easily previewed during design without running the application; however, in this case we must also specify the location of our root component DOM Element using a
"data-field"
matching the value of the @Templated annotation. There is no limit to how many component classes may share a given HTML template.
@Templated("my-template.html#login-form")
public class LoginForm extends Composite {
/* Specifies that <... data-field="login-form"> be used as the root Element of this Widget */
}
Notice the corresponding HTML data-field attribute in the form Element below, and also note that multiple components may use the same template provided that they specify a corresponding
data-field
attribute. Also note that two or more components may share the same template
data-field
DOM elements; there is no conflict since components each receive a unique copy of the template DOM from the designated
data-field
at runtime (or from the root element if a fragment is not specified.)
<!DOCTYPE html>
<html lang="en">
<head>
<title>A full HTML snippit</title>
</head>
<body>
<div>
<form data-field="login-form">
<legend>Log in to your account</legend>
<label for="username">Username</label>
<input id="username" type="text" placeholder="Username">
<label for="username">Password</label>
<input id="password" type="password" placeholder="Password">
<button>Log in</button>
<button>Cancel</button>
</form>
</div>
<hr>
<footer data-field="theme-footer">
<p>(c) Company 2012</p>
</footer>
</body>
</html>
For example's sake, the component below could also use the same template. All it needs to do is reference the template name, and specify a fragment.
@Templated("my-template.html#theme-footer")
public class Footer extends Composite {
/* Specifies that <... data-field="theme-footer"> be used as the root Element of this Widget */
}
Now that we have created the @Templated Composite component and an HTML template, we can start wiring in functionality and behavior; this is done by annotating fields and methods to replace specific sub-elements of the template DOM with other Widgets. We can even replace portions of the template with other Errai UI Widgets!
In order to composite Widgets into the template DOM, you must annotate fields in your @Templated Composite component with @DataField, and mark the HTML template Element with a corresponding
data-field
attribute. This informs Errai UI that the contents of the field should replace the element marked by data-field in the template; thus, fields annotated with @DataField must either be @Inject or initialize valid Widget or Element instances.
@Templated
public class LoginForm extends Composite {
// This element must be initialized manually because Element is not @Inject-able*/
@DataField
private Element form = DOM.createForm();
// If not otherwise specified, the data-field name defaults to the name of the field; in this case, the data-field name would be "username"
@Inject
@DataField
private TextBox username;
// The data-field name may also be specified manually
@Inject
@DataField("pass")
private PasswordTextBox password;
// We can also choose to instantiate our own Widgets. Injection is not required.
@DataField
private Button submit = new Button();
}
Important
Note: Field, method, and constructor injection are all supported by @DataField.
We must also add data-field attributes to the corresponding locations in our template HTML file. This, combined with the @DataField annotation in our Composite component allow Errai UI to determine where and what should be composited when creating component instances.
<form data-field="form">
<legend>Log in to your account</legend>
<label for="username">Username</label>
<input data-field="username" id="username" type="text" placeholder="Username">
<label for="password">Password</label>
<input data-field="pass" id="password" type="password" placeholder="Password">
<button data-field="submit">Log in</button>
<button>Cancel</button>
</form>
Now, when we run our application, we will be able to interact with these fields in our Widget.
Three things are merged or modified when Errai UI creates a new Composite component instance:
Element attributes are merged from the template to the component
DOM Elements are merged from the component to the template
Template element inner text and inner HTML are preserved when the given
@DataFieldWidgetimplementsHasTextorHasHTML
@Templated
public class StyledComponent extends Composite {
@Inject
@DataField("field-1")
private Label div = new Label();
public StyledComponent() {
div.getElement().setAttribute("style", "position: fixed; top: 0; left: 0;");
this.getElement().setId("outer-id");
}
}
<form>
<span data-field="field-1" style="display:inline;"> This element will become a div </span>
</form>
This text will be ignored.
<form id="outer-id">
<div data-field="field-1" style="display:inline;"> This element will become a div </div>
</form>
But why does the output look the way it does? Some things happened that may be unsettling at first, but we find that once you understand why these things occur, you'll find the mechanisms extremely powerful.
When styling your templates, you should keep in mind that all attributes defined in the template file will take precedence over any preset attributes in your Widgets. This "attribute merge" occurs only when the components are instantiated; subsequent changes to any attributes after Widget construction will function normally. In the example we defined a Composite component that applied several styles to a child Widget in its constructor, but we can see from the output that the styles from the template have overridden them. If styles must be applied in Java, instead of the template,
@PostConstruct
or other methods should be favored over constructors to apply styles to fully-constructed Composite components.
Element composition, however, functions inversely from attribute merging, and the
<span>
defined in our template was actually be replaced by the
<div>
Label in our Composite component field. This does not, however, change the behavior of the attribute merge - the new
<div>
was still be rendered inline, because we have specified this style in our template, and the template always wins in competition with attributes set programatically before composition occurs. In short, whatever is in the
@DataField
in your class will replace the
data-field
in your template.
Additionally, because
Label
implements both
HasText
and
HasHTML
(only one is required,) the contents of this <span> "field-1" Element in the template were preserved; however, this would not have been the case if the
@DataField
specified for the element did not implement
HasText
or
HasHTML
. In short, if you wish to preserve text or HTML contents of an element in your template, you can do one of two things: do not composite that Element with a
@DataField
reference, or ensure that the Widget being composited implements
HasText
or
HasHTML
.
Dealing with User and DOM Events is a reality in rich web development, and Errai UI provides several approaches for dealing with all types of browser events using its "quick handler" functionality. It is possible to handle:
GWT events on Widgets
GWT events on DOM Elements
Native DOM events on Elements
Important
It is not possible to handle Native DOM events on Widgets because GWT overrides native event handlers when Widgets are added to the DOM. You must programatically configure such handlers after the Widget has been added to the DOM.
Each of the three scenarios mentioned above use the same basic programming model for event handling: Errai UI wires methods annotated with
@EventHandler("my-data-field")
(
event handler methods
) to handle events on the corresponding
@DataField("my-data-field")
in the same component. Event handler methods annotated with a bare
@EventHandler
annotation (no annotation parameter) are wired to receive events on the @Templated component itself.
Probably the simplest and most common use-case, this approach handles GWT Event classes for Widgets that explicitly handle the given event type. If a Widget does not handle the Event type given in the
@EventHandler
method's signature, the application will fail to compile and appropriate errors will be displayed.
@Templated
public class WidgetHandlerComponent extends Composite {
@Inject
@DataField("b1")
private Button button;
@EventHandler("b1")
public void doSomethingC1(ClickEvent e) {
// do something
}
}
Errai UI also makes it possible to handle GWT events on native Elements which are specified as a
@DataField
in the component class. This is useful when a full GWT Widget is not available for a given Element, or for GWT events that might not normally be available on a given Element type. This could occur, for instance, when clicking on a
<div>
, which would normally not have the ability to receive the GWT
ClickEvent
, and would otherwise require creating a custom DIV Widget to handle such an event.
@Templated
public class ElementHandlerComponent extends Composite {
@DataField("div-1")
private DivElement button = DOM.createDiv();
@EventHandler("div-1")
public void doSomethingC1(ClickEvent e) {
// do something
}
}
The last approach is handles the case where native DOM events must be handled, but no such GWT event handler exists for the given event type. Alternatively, it can also be used for situations where Elements in the template should receive events, but no handle to the Element the component class is necessary (aside from the event handling itself.) Native DOM events do not require a corresponding
@DataField
be configured in the class; only the HTML
data-field
template attribute is required.
<div>
<a data-field="link" href="/page"
<div data-field="div"> Some content </div>
</div>
The
@SinkNative
annotation specifies (as a bit mask) which native events the method should handle; this sink behaves the same in Errai UI as it would with
DOM.sinkEvents(Element e, int bits)
. Note that a
@DataField
reference in the component class is optional.
Important
Only one @EventHandler may be specified for a given data-field when @SinkNative is used to handle native DOM events.
@Templated
public class QuickHandlerComponent extends Composite {
@DataField
private AnchorElement link = DOM.createAnchor().cast();
@EventHandler("link")
@SinkNative(Event.ONCLICK | Event.ONMOUSEOVER)
public void doSomething(Event e) {
// do something
}
@EventHandler("div")
@SinkNative(Event.ONMOUSEOVER)
public void doSomethingElse(Event e) {
// do something else
}
}
A recurring implementation task in rich web development is writing event handler code for updating model objects to reflect input field changes in the user interface. The requirement to update user interface fields in response to changed model values is just as common. These tasks require a significant amount of boilerplate code which can be alleviated by Errai. Errai's data binding module provides the ability to bind model objects to user interface fields, so they will be kept in sync automatically. While the module can be used on its own, it can cut even more boilerplate when integrated with Errai UI.
In the following example, all
@DataFields
annotated with
@Bound
have their contents bound to properties of the data model (a
User
object). The model object is provided by an injected
DataBinder
instance annotated with
@AutoBound
, which indicates automatic binding should be carried out. This works whether the
DataBinder
is injected into a field or a constructor.
@Templated
public class LoginForm extends Composite {
@Inject
@Bound
@DataField
private TextBox username;
@Inject
@Bound
@DataField
private PasswordTextBox password;
@DataField
private Button submit = new Button();
private User user;
@Inject
public LoginForm(@AutoBound DataBinder<User> userBinder) {
this.user = userBinder.getModel();
}
}
Now the user object and the username and password fields are automatically kept in sync. No event handling code needs to be written for updating the user object in response to input field changes and no code needs to be written for updating the user interface fields when the model object changes (when
setUsername
or
setPassword
is called).
By default, bindings are determined by matching
@DataField
names to property names on the model object. In the example above, the
@DataField
username
was automatically bound to the JavaBeans property
username
of the model object. If the
@DataField
name does not match the model property name, you can use the
property
attribute of the
@Bound
annotation to specify the name of the property. The property can be a simple name (for example, "name") or a property chain (for example,
user.address.streetName
). When binding to a property chain, all properties but the last in the chain must refer to @Bindable values.
The following example illustrates all three scenarios:
@Bindable
public class Address {
private String line1;
private String line2;
private String city;
private String stateProv;
private String country;
// getters and setters
}
@Bindable
public class User {
private String name;
private Date dob;
private Address address;
// getters and setters
}
@Templated
public class UserWidget {
@Inject @AutoBound DataBinder<User> user;
@Inject @Bound TextBox name;
@Inject @Bound("dob") DatePicker dateOfBirth;
@Inject @Bound("address.city") TextBox city;
}
In
UserWidget
above, the
name
text box is bound to
user.name
using the default name matching; the
dateOfBirth
date picker is bound to
user.dob
using a simple property name mapping; finally, the
city
text box is bound to
user.address.city
using a property chain. Note that the
Address
class is required to be
@Bindable
in this case.
More often than not you will need to bind a list of model objects so that every object in the list is bound to a corresponding widget. This task can be simplified using Errai UI's
ListWidget
class. Here's an example of binding a list of users using the
UserWidget
class from the previous example.
@Templated
public class UserList extends Composite {
@Inject @DataField ListWidget<User, UserWidget> userList;
@PostConstruct
public void init() {
List<User> users = .....
userList.setItems(users);
}
}
Calling
setItems
on the
userList
causes an instance of
UserWidget
to be displayed for each user in the list. The
UserWidget
is then bound to the corresponding user object. By default, the widgets are arranged in a vertical panel. However,
ListWidget
can be subclassed to provide alternative behaviour. In the following example, we use a horizontal panel to display the widgets.
public class UserList extends ListWidget<User, UserWidget> {
public UserList() {
super(new HorizontalPanel());
}
@PostConstruct
public void init() {
List<User> users = .....
setItems(users);
}
@Override
public Class<UserWidget> getItemWidgetType() {
return UserWidget.class;
}
}
The
@Bound
annotation further allows to specify a converter to use for the binding (see
Specifying Converters
for details). This is how a binding specific converter can be specified on a data field:
@Inject
@Bound(converter=MyDateConverter.class)
@DataField
private TextBox date;
Errai's
DataBinder
also allows to register
PropertyChangeHandlers
for the cases where keeping the model and UI in sync is not enough and additional logic needs to be executed (see
Property Change Handlers
for details).
Using Composite components to build up a hierarchy of widgets functions exactly the same as when building hierarchies of GWT widgets. The only distinction might be that with Errai UI,
@Inject
is preferred to manual instantiation.
@Templated
public class ComponentOne extends Composite {
@Inject
@DataField("other-comp")
private ComponentTwo two;
}
Templating would not be complete without the ability to inherit from parent templates, and Errai UI also makes this possible using simple Java inheritance. The only additional requirement is that Composite components extending from a parent Composite component must also be annotated with @Templated, and the path to the template file must also be specified in the child component's annotation. Child components may specify
@DataField
references that were omitted in the parent class, and they may also override
@DataField
references (by using the same
data-field
name) that were already specified in the parent component.
Extension templating is particularly useful for creating reusable page layouts with some shared content (navigation menus, side-bars, footers, etc...,) where certain sections will be filled with unique content for each page that extends from the base template; this is commonly seen when combined with the MVP design pattern traditionally used in GWT applications.
<div class="container">
<div data-field="header"> Default header </div>
<div data-field="content"> Default content </div> <div data-field="footer"> Default footer </div>
</div>
This component provides the common features of our page layout, including header and footer, but does not specify any content. The missing data-field will be supplied with unique content by the individual page components extending from this parent component.
@Templated
public class PageLayout extends Composite {
@Inject
@DataField
private HeaderComponent header;
@Inject
@DataField
private FooterComponent footer;
@PostConstruct
public final void init() {
// do some setup
}
}
We are free to fill in the missing "content"
data-field
with a Widget of our choosing. Note that it is not required to fill in all omitted data-field references.
@Templated("PageLayout.html")
public class LoginLayout extends PageLayout {
@Inject
@DataField
private LoginForm content;
}
We could also have chosen to override one or more
@DataField
references defined in the parent component, simply by specifying a
@DataField
with the same name in the child component, as is done with the "footer"
data-field
below.
@Templated("PageLayout.html")
public class LoginLayout extends PageLayout {
@Inject
@DataField
private LoginForm content;
/* Override footer defined in PageLayout */
@Inject
@DataField
private CustomFooter footer;
}