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 components:

As previously mentioned, components in Errai UI consist of a Java class (the templated bean), an HTML file (the template), and an optional CSS file (the template stylesheet). A Java class is a templated bean if the type is annotated with @Templated.

@Templated("my-template.html")

public class LoginForm {

   /* Looks for my-template.html in LoginForm's package */

}

@Templated("/org/example/my-template.html")

public class LoginForm {

   /* Looks for my-template.html in package org.example */

}

@Templated(value="home.html", provider=ServerTemplateProvider.class)

public class LoginForm {

  /* Makes an HTTP request for the relative path "home.html" */

}

@Templated(provider=MyTemplateProvider.class)

public class LoginForm {

  /* Makes an HTTP request for the relative path "home.html" */

}


@Dependent

public class MyTemplateProvider implements TemplateProvider {


  @Override

  public void provideTemplate(String location, TemplateRenderingCallback renderingCallback) {

    String template;


    /*

     * Generate the template String.

     * Note: The location parameter is the value from the @Templated annotation.

     */


    renderingCallback.renderTemplate(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 component to add behavior, and use additional components to add functionality to the template. There is no limit to how many templated beans may share a given HTML template.

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

@Templated("my-template.html#theme-footer")

public class Footer {

   /* Specifies that <... id="theme-footer"> be used as the root Element of this Widget */

}

Now that we know how to create a @Templated bean 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. We can even replace portions of the template with other Errai UI components!

/*

* Here the template file is implicitly LoginForm.html.

* The root element has id, class, or data-field "form".

*/

@Templated("#form")

public class LoginForm {

   // This is the root element of the template, for adding this component to the DOM.

   @Inject

   @DataField

   private Form form;


   // If not otherwise specified, the name to match in the HTML template defaults

   // to the name of the field; in this case, the name would be "username"

   @Inject

   @DataField

   private TextInput username;


   // The name to reference in the template can also be specified manually

   @Inject

   @DataField("pass")

   private PasswordInput password;


   // We can also choose to instantiate our own data fields. Injection is not required.

   @DataField

   private Button submit = (Button) Window.getDocument().createElement("button");

}

<div class="root">

  <h1>Hello World!</h1>

</div>

@Templated

public class MyBean {

  @Inject @DataField Div root;

}

<div class="root">

  <h1>Hello World!</h1>

</div>

@Templated

public class MyBean implements org.jboss.errai.ui.client.local.api.IsElement {

}

@EntryPoint

public class Setup {

  @Inject MyBean component;

  @Inject Document doc;


  @PostConstruct

  public void attachBean() {

    // The default implementation automatically returns

    // the correct root element.

    HTMLElement rootElement = component.getElement();

    doc.getBody().appendChild(rootElement);

  }

}

@JsType(isNative = true)

@Element("form")

public interface NativeForm {

  // Element methods and properties go here

}

/*

* Like the component from the previous example, but with a custom element wrapper as its root.

*/

@Templated("#form")

public class LoginForm {

   // Now the root element is our custom JsType

   @Inject

   @DataField

   private NativeForm form;


   @Inject

   @DataField

   private TextInput username;


   @Inject

   @DataField("pass")

   private PasswordInput password;


   @DataField

   private Button submit = (Button) Window.getDocument().createElement("button");

}

@JsType(isNative = true)

@Element({ "h1", "h2", "h3", "h4", "h5", "h6" })

public interface NativeHeading {

  // Heading element methods and properties go here

}

@Templated

public class Component {

  // Injects a gwt-user HeadingElement with tag name "h1"

  @Inject

  @Named("h1")

  @DataField

  private HeadingElement h1;


  // Injects a NativeHeading wrapper for an "h6" element

  @Inject

  @Named("h6")

  @DataField

  private NativeHeading h6;

}

@Templated

public class ErroneousTemplate {

   @Inject @DataField

   private Div eat;


   @Inject @DataField

   private Div drink;

}

<form id="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 data-field="pass" id="password" type="password" placeholder="Password">



  <button id="submit">Log in</button>

  <button>Cancel</button>

</form>

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

@Templated

public class StyledComponent implements IsElement {

   @Inject

   @DataField("field-1")

   private Div div;


   public StyledComponent() {

      CSSStyleDeclaration style = div.getStyle();

      style.setProperty("position", "fixed");

      style.setProperty("top", "0");

      style.setProperty("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>

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:

@Templated

public class ElementHandlerComponent {


   @Inject

   @DataField("b1")

   private ButtonElement button;


   @EventHandler("b1")

   public void doSomething(@ForEvent("click") Event e) {

     // do something

   }

}

@Templated

public class ElementHandlerComponent {


   @Inject

   @DataField

   private AnchorElement link;


   @EventHandler("link")

   public void doSomething(FocusEvent e) {

     // do something

   }

}

@Templated

public class WidgetAndElementHandlerComponent {


   @Inject

   @DataField

   private TextBox input;


   // Handles focus-related events on the

   // underlying HTML element of the TextBox field.

   @EventHandler("input")

   public void doSomething(FocusEvent e) {

     // do something

   }


   // Handles dblclick events for the element in the

   // template with id/class/data-field="button".

   @EventHandler("button")

   public void onClick(@ForEvent("dblclick") MouseEvent e) {

     // do something

   }

}

@Templated

public class WidgetHandlerComponent extends Composite {


   @Inject

   @DataField("b1")

   private Button button;


   @EventHandler("b1")

   public void doSomethingC1(ClickEvent e) {

     // do something

   }

}

@Templated

public class ElementHandlerComponent extends Composite {


   @DataField("div-1")

   private DivElement button = DOM.createDiv();


   @EventHandler("div-1")

   public void doSomethingC1(ClickEvent e) {

     // do something

   }

}

<div>

   <a id="link" href="/page">this is a hyperlink</a>

   <div data-field="div"> Some content </div>

</div>

@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

  }

}

Using asynchronous Javascript calls often make realizing the benefits of modern browsers difficult when it comes to form submission. But there is now a base class in Errai UI for creating @Templated form widgets that are perfect for tasks such as creating a login form.

@Dependent

@Templated

public class LoginForm extends AbstractForm { 


  @Inject

  private Caller<AuthenticationService> authenticationServiceCaller;


  @Inject

  @DataField

  private TextBox username;


  @Inject

  @DataField

  private PasswordTextBox password;


  @DataField

  private final FormElement form = DOM.createForm(); 


  @Inject

  @DataField

  private Button login; 


  @Override

  protected FormElement getFormElement() {

    return form; 

  }


  @EventHandler("login")

  private void loginClicked(ClickEvent event) {

    authenticationServiceCaller.call(new RemoteCallback<User>() {


      @Override

      public void callback(User response) {

        // Now that we're logged in, submit the form

        submit(); 

      }

    }).login(username.getText(), password.getText());

  }


}

<div>

  <form data-field="form">

    <input type="text" name="username" data-field="username">

    <input type="password" name="password" data-field="password">

    <button data-field="login">Sign In</button>

  </form>

</div>

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.

@Templated

public class LoginForm {


   @Inject

   @Model

   private User user;


   @Inject

   @Bound

   @DataField

   private InputElement name;


   @Inject

   @Bound

   @DataField

   private PasswordTextBox password;


   @DataField

   private Button submit = new Button();

}

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

@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 String password;

  private Date dob;

  private Address address;

  private List<Role> roles;


  // getters and setters

}


@Templated

public class UserComponent {

  @Inject @AutoBound DataBinder<User> user;

  @Inject @Bound InputElement name;

  @Inject @Bound(property="dob") DatePicker dateOfBirth;

  @Inject @Bound(property="address.city") TextBox city;

}

@Templated

public class UserWidget implements HasModel<User> {

  @Inject @AutoBound DataBinder<User> userBinder;

  @Inject @Bound InputElement name;

  @Inject @Bound(property="dob") DatePicker dateOfBirth;

  @Inject @Bound(property="address.city") TextBox city;


  public User getModel() {

    userBinder.getModel();

  }


  public void setModel(User user) {

    userBinder.setModel(user);

  }

}

@Templated

public class MyComponent {


  @Inject @DataField ListWidget<User, UserComponent> userListWidget;


  @PostConstruct

  public void init() {

    List<User> users = .....

    userListWidget.setItems(users);

  }

}

public class UserListWidget 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;

  }

}

@Templated

public class UserDetailView {


   @Inject

   @Bound

   @DataField

   private InputElement name;


   @Inject

   @Bound

   @DataField

   private PasswordTextBox password;


   @Inject

   @Bound

   @DataField

   private ListWidget<Role, RoleWidget> roles;


   @DataField

   private Button submit = new Button();


   @Inject @Model

   private User user;

}

@Inject

@Bound(converter=MyDateConverter.class)

@DataField

private TextBox date;

Using components to build up a hierarchy of UI componenets functions exactly the same as when building hierarchies of GWT widgets or DOM elements. The only distinction might be that with Errai UI, @Inject is preferred to manual instantiation.

@Templated

public class ComponentOne {


   @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 components extending from a parent 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.

<div class="container">

   <div id="header"> Default header </div>

   <div id="content"> Default content </div>

   <div id="footer"> Default footer </div>

</div>

@Templated

public class PageLayout {


   @Inject

   @DataField

   private HeaderComponent header;


   @Inject

   @DataField

   private FooterComponent footer;


   @PostConstruct

   public final void init() {

      // do some setup

   }

}

@Templated("PageLayout.html")

public class LoginLayout extends PageLayout {


   @Inject

   @DataField

   private LoginForm content;


}

@Templated("PageLayout.html")

public class LoginLayout extends PageLayout {


   @Inject

   @DataField

   private LoginForm content;


   /* Override footer defined in PageLayout */

   @Inject

   @DataField

   private CustomFooter footer;


}

When developing moderately-complex web applications with Errai, you may find yourself needing to do quite a bit of programmatic style changes. One common case is 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.

@StyleBinding

@Retention(RetentionPolicy.RUNTIME)

public @interface Admin {

}

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

@EntryPoint

@Templated

public class HelloWorldForm {

  @Inject @Admin @DataField ButtonElement deleteButton;

  @Inject SessionManager sessionManager;



  @EventHandler("deleteButton")

  private void handleSendClick(ClickEvent event) {

    // do some deleting!

  }


  @Admin

  private void applyAdminStyling(Style style) {

    if (!sessionManager.isAdmin()) {

      style.setVisibility(Style.Visibility.HIDDEN);

    }

  }

}

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.

The above example took at Style object as a parameter, but it is also possible to use an Element. So the applyAdminStyling method above could have also been written like this:

  @Admin

  private void applyAdminStyling(Element element) {

    if (!sessionManager.isAdmin()) {

      element.addClassName("disabled");

    }

  }

The CSS class "disabled" could apply the same style as before ("visibility: hidden") or it could have more complex behaviour that is dependent on the element type.

User interfaces often need to be available in different languages. Errai’s i18n support makes it easier for you to publish your web app in multiple languages. This section explains how to use this feature in your application.

{
"StoresPage.Stores!" : "Stores!",
"WelcomePage.As_you_move_toward_a_more_and_more_declarative_style,_you_allow_the_compiler_and_the_framework_to_catch_more_mistakes_up_front._-734987445" : "As you move toward a more and more declarative style, you allow the compiler and the framework to catch more mistakes up front. Broken links? A thing of the past!"
}

StoresPage.Stores! = Stores!
WelcomePage.As_you_move_toward_a_more_and_more_declarative_style,_you_allow_the_compiler_and_the_framework_to_catch_more_mistakes_up_front._-734987445 = As you move toward a more and more declarative style, you allow the compiler and the framework to catch more mistakes up front. Broken links? A thing of the past!

<html>

<body>

  <div id="content">

  <p data-i18n-key="welcome">Welcome to errai-ui i18n.</p>

<div>

...

{
    "TemplatedClassName.welcome": "Willkommen bei Errai-ui i18n."
}

TemplatedClassName.welcome=Willkommen bei Errai-ui i18n.

{
    "welcome": "Willkommen bei Errai-ui i18n."
}

welcome=Willkommen bei Errai-ui i18n.

<div id=navbar data-role=dummy>

  <div class="navbar navbar-fixed-top">

    <div class=navbar-inner>

      <div class=container>

        <span class=brand>Example Navbar</span>

        <ul class=nav>

          <li><a>Item</a>

          <li><a>Item</a>

        </ul>

      </div>

    </div>

  </div>

</div>

@Templated

public class NavBar {


  @Inject

  private LocaleSelector selector;


  @Inject @DataField @OrderedList

  ListWidget<Locale, LanguageItem> language;


  @AfterInitialization

  public void buildLanguageList() {

    language.setItems(new ArrayList<Locale>(selector.getSupportedLocales()));

  }


...

// in LanguageItem we add a click handler on a link


  @Inject

  Navigation navigation;


  @Inject

  private LocaleSelector selector;


  link.addClickHandler(new ClickHandler() {

      @Override

      public void onClick(ClickEvent event) {

        selector.select(model.getLocale());

        navigation.goTo(navigation.getCurrentPage().name());

      }

    });

package org.example.ui.client.local;


public class AppMessages {


   @TranslationKey(defaultValue = "I guess something happened!")

   public static final String CUSTOM_MESSAGE = "app.custom-message";


   @TranslationKey(defaultValue = "Hey {0}, I just told you something happened!")

   public static final String CUSTOM_MESSAGE_WITH_NAME = "app.custom-message-with-name";

}

package org.example.ui.client.local;


@Dependent

@Templated

public class CustomComponent extends Composite {


   @Inject

   private TranslationService translationService;


   @Inject

   @DataField

   private Button someAction;


   @EventHandler("someAction")

   private void doLogin(ClickEvent event) {


      // do some action that may require a notification sent to the user


      String messageToUser = translationService.format(AppMessages.CUSTOM_MESSAGE);

      Window.alert(messageToUser);


      String username = getCurrentUserName();

      String messageToUserWithName = translationService.format(AppMessages.CUSTOM_MESSAGE_WITH_NAME, username);

      Window.alert(messageToUserWithName);

   }

}

Errai also supports LESS stylesheets for @Templated. You can specify a CSS or LESS stylesheet path for a component with the stylesheet attribute of @Templated, as in the example below:

package org.jboss.errai.example;


@Templated(stylesheet = "main.less")

public class StyledComponent {

}

For the above example, during GWT compilation Errai will load the LESS stylesheet from the classpath (in this case with the path org/jboss/errai/example/main.less) and compile it. At runtime the compiled CSS will be loaded.

You can omit the stylesheet attribute if your LESS stylsheet follows the standard Errai UI naming conventions. For example:

package org.jboss.errai.example;


@Templated

public class StyledComponent {

}

Errai will automatically find and compile a LESS stylesheet for this template if it exists on the classpath at this path: org/jboss/errai/example/StyledComponent.less