Skip to end of metadata
Go to start of metadata
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.
Get Adobe Flash player

Get started

The Errai UI module is directly integrated with 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:

App.gwt.xml

pom.xml

The easiest way to get Errai UI on your classpath is to depend on the special errai-javaee-all artifact, which brings in most Errai modules:

Or if you prefer to manage your project's dependency in a finer-grained way, you can depend on errai-ui directly:

Working Demo

If you work better by playing with a finished product, you can see a simple client-server project implemented using Errai UI here.

Use Errai UI Composite components

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.

Inject a single instance

Inject multiple instances (for iteration)

Create a @Templated Composite component

Custom components in Errai UI are single classes extending from com.google.gwt.user.client.ui.Composite, and must be annotated with @Templated.

Basic component

Custom template names

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:

Fully qualified template paths are also supported, but must begin with a leading '/':

Create an HTML template

Templates in Errai UI may be designed either as an HTML snippet or as a full HTML document. You can even take an existing HTML page and use it as a template. With either approach, the id, class, and data-field attributes in the template identify elements by name. These elements and their children 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.

Select a template from a larger HTML file

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 component's root DOM Element using a "data-field", id, or class attribute matching the value of the @Templated annotation. There is no limit to how many component classes may share a given HTML template.

Notice the corresponding HTML id attribute in the form Element below (we could have used data-field or class instead). Note that multiple components may use the same template provided that they specify a corresponding data-field, id, or class attribute. Also note that two or more components may share the same DOM elements; there is no conflict since components each receive a unique copy of the template DOM rooted at the designated element at runtime (or from the root element if a fragment is not specified.)

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.

Use other Widgets in a composite component

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!

Annotate Widgets in the template with @DataField

In order to composite Widgets into the template DOM, you annotate fields in your @Templated Composite component with @DataField, and mark the HTML template Element with a correspondingly named data-field, id, or class attribute. This informs Errai UI which element in the template the Widget should replace. All replacements happen while the @Templated Composite component is being constructed; thus, fields annotated with @DataField must either be {{@Inject}}ed or provide their own Widget or Element instances in field initializers.

Note: Field, method, and constructor injection are all supported by @DataField.


Add corresponding attributes to the HTML template

Each @DataField reference in the Java class must match an element in the HTML template. The matching of Java references to HTML elements is performed as follows:

  1. A name for the Java reference is determined. If the @DataField annotation has a value argument, that is used as the reference name. For fields, the default reference name is the field name. Method and constructor parameters have no default name, so they must always specify a value.
  2. If there is an element in the HTML template with attribute data-field=name, the Java reference will point to this element. If there is more than one such element, the Java reference points to the first.
  3. Otherwise, if there is an element in the HTML template with attribute id=name, the Java reference will point to this element. If there is more than one such element, the Java reference points to the first.
  4. Otherwise, if there is an element in the HTML template with a CSS style class name, the Java reference will point to this element. If there is more than one such element, the Java reference points to the first. For elements with more than one CSS style, each style name is considered individually. For example:

    matches Java references named eat, drink, or be-merry.

  5. If no matching element is found by this point, it is an error.

If more than one Java reference matches the same HTML element in the template, it is an error. For example,
given a template containing the element <div class="eat drink be-merry">, the following Java code
is in error:

because both fields eat and drink refer to the same HTML div element.

So now we must ensure there are data-field, id, or class attributes in the right places 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.

Now, when we run our application, we will be able to interact with these fields in our Widget.

How HTML templates are merged with Components

Three things are merged or modified when Errai UI creates a new Composite component instance:

  1. Element attributes are merged from the template to the component
  2. DOM Elements are merged from the component to the template
  3. Template element inner text and inner HTML are preserved when the given @DataField Widget implements HasText or HasHTML

Example

Composite component class:
Template:
Output / result:

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.

Element attributes (template wins)

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.

DOM Elements (component field wins)

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 inside the @DataField in your class will replace the children of the corresponding element in your template.

Inner text and inner HTML (preserved when component implements HasText or HasHTML)

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.

Event handlers

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:

  1. GWT events on Widgets
  2. GWT events on DOM Elements
  3. Native DOM events on Elements
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.

Concepts

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.

GWT events on Widgets

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.

GWT events on DOM Elements

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.

Native DOM events on Elements

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, id, or class template attribute is required.

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.

Only one @EventHandler may be specified for a given template element when @SinkNative is used to handle native DOM events.


Data Binding

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 automatically be kept in sync. While the module can be used on its own, it can cut even more boilerplate when used together 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 injected and annotated with @Model, which indicates automatic binding should be carried out. Alternatively, the model object could be provided by an injected DataBinder instance annotated with @AutoBound, see Declarative Binding for details.

Now the user object and the username and password fields in the UI are automatically kept in sync. No event handling code needs to be written to update the user object in response to input field changes and no code needs to be written to update the UI fields when the model object changes. So, with the above annotations in place, it will always be true that user.getUsername().equals(username.getText()) and user.getPassword().equals(password.getText()).

Default, Simple, and Chained Property Bindings

By default, bindings are determined by matching field names to property names on the model object. In the example above, the field name was automatically bound to the JavaBeans property name of the model (user object). If the field 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:

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.

Binding of Lists

Often 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 accomplished using Errai UI's ListWidget class. Here's an example of binding a list of users using the UserWidget class from the previous example. First, we need to enhance UserWidget to implement HasModel.

Now we can use UserWidget to display items in a list.

Calling setItems on the userListWidget 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 also be subclassed to provide alternative behaviour. In the following example, we use a horizontal panel to display the widgets.

Binding lists with @Bound

An instance of ListWidget can also participate in automatic bindings using @Bound. In this case, setItems never needs to be called manually. The bound list property and displayed items will automatically be kept in sync. In the example below a list of user roles is bound to a ListWidget that displays and manages a RoleWidget for each role in the list. Every change to the list returned by user.getRoles() will now trigger a corresponding update in the UI.

Data Converters

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:

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).

Nest Composite components

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.

Extend Composite components

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.

Template

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.

Parent component

This component provides the common features of our page layout, including header and footer, but does not specify any content. The missing @DataField "content" will be provided by the individual page components extending from this parent component.

Child component

We are free to fill in the missing "content" @DataField with a Widget of our choosing. Note that it is not required to fill in all omitted @DataField references.

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.

Stylesheet binding

When developing moderately-complex web applications with Errai, you may find yourself needing to do quite a bit of programmatic style changes. A common case being: showing or enabling controls only if a user has the necessary permissions to use them. One part of the problem is securing those features from being used, and the other part – which is an important usability consideration – is communicating that state to the user.

Let's start with the example case I just described. We have a control that we only want to be visible if the user is an admin. So the first thing we do is create a style binding annotation.

This defines Admin as a stylebinding now we can use it like this:

Now before the form is shown to the user the applyAdminStyling method will be executed where the sessionManager is queried to see if the user is an admin if not the delete button that is also annotated with @Admin will be hidden from the view.

In addition when using this in conjunction with Errai Databinding. Any Errai UI component which uses @AutoBound, will get live updating of the style rules for free, anytime the model changes. Allowing dynamic styling based on user input and other state changes.

Internationalization (i18n)

User interfaces often need to be available in multiple languages. To get started with Errai's internationalization support, simply put the @Bundle("bundle.json") annotation on your entry point and add an empty bundle.json file to your classpath (e.g. to src/main/java or src/main/resources). Of course, you can name it differently.

Errai will scan your HTML templates and process all text elements to generate key/value pairs for translation. It will generate a file called errai-bundle-all.json and put it in your .errai directory. You can copy this generated file and use it as a starting point for your custom translation bundles. If the text value is longer than 128 characters the key will get cut off and a hash appended at the end.

The translation bundle files use the same naming scheme as Java (e.g. bundle_nl_BE.json for Belgian Dutch and bundle_nl.json for plain Dutch). Errai will also generate a file called errai-bundle-missing.json in the .errai folder containing all template values for which no translations have been defined. You can copy the key/value pairs out of this file to create our own translations:

If you want to use your own keys instead of these generated ones you can specify them in your templates using the data-i18n-key attribute:

By adding this attribute in the template you can translate it with the following:

Because your templates are designer templates and can contain some mock data that doesn't need to be translated, Errai has the ability to indicate that with an attribute data-role=dummy:

Here the template fills out a navbar with dummy elements, useful for creating a design, adding data-role=dummy will not only exclude it form being translated it will also strip the children nodes from the template that will be used by the application.

When you have setup a translation of your application Errai will look at the browser locale and select the locale, if it's available, if not it will use the default (bundle.json). If the users of your application need to be able to switch the language manually, Errai offers a pre build component you can easily add to your page:LocaleListBox will render a Listbox with all available languages. If you want more control of what this language selector looks like there is also a LocaleSelector that you can use to query and select the locale for example:

Extended styling with LESS 

Errai also supports LESS stylesheets. To get started using these you'll have to create a LESS stylesheet and place it on the classpath of your project. Errai will convert the LESS stylesheet to css preform optimisations on it and ensure that is get injected into the pages of your application. It will also obfuscate the class selectors and replace the use of those in your templates. To be able to use the selectors in your code you can use: 

Finally it will also add any deferred binding properties to the top of your LESS stylesheet, so for example you could use the user.agent in LESS like this:

Because a dot is not allowed in LESS variables it's replaced with an underscore, so in the example above class1 will have a black background on Safari and Chrome and white on Firefox. On the top of this LESS stylesheet @user_agent: "safari" will get generated.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Nov 19, 2012

    Is the Get Flash Player table appropriate to Errai UI? I'm missing the reason why it is mentioned in the beginning of the page.

    1. Nov 19, 2012

      Maybe you should get Flash Player and find out why it's there ;) There's a video tutorial embedded in the page.

      1. Nov 19, 2012

        I'm pretty sure that I have Flash Player enabled in my browser:

        Shockwave Flash
        Version: 11.2 r202
        Location: /opt/google/chrome/plugins/libflashplayer.so
        Type: NPAPI

        Any chance to have html5 video instead?

        1. Nov 19, 2012

          Strange... well. It works for me and it's using standard Vimeo embedder, so I'm not sure what the problem is!

          1. Apr 22, 2013

            It works for me in Firefox, but not in chrome.  I think Karel was using chrome, too.