Errai: The browser as a platform

Thursday, November 10, 2016

Errai 4.0.0.Beta4 released!


Errai 4.0.0.Beta4 is now available. This release contains mostly bug fixes, but here are some noteworthy changes:
  • Upgrade GWT to 2.8.0 and Guava to 20.0
  • The Errai Tutorial now showcases Errai's JS interop integration

Errai Tutorial Enhancments

A major vision of Errai 4 has been more support for working directly with the DOM and more support for using JS interop. With this latest round of enhancements, the Errai Tutorial now showcases this vision and below I'll highlight some of the major features in action.

UI Components without GWT Widgets

The Errai Tutorial now showcases UI components built without any GWT widgets [1] [2]. These components are built with Errai templating using JS interop wrappers for interacting with the DOM; Element wrappers are used in place of GWT widgets and DOM events in place of GWT widget events.

One big advantage of this approach is that the markup of these UI components at runtime is exactly the same as the template HTML. Because GWT widgets are often implemented with multiple tags and custom CSS classes, using widgets as @DataFields can result in UI components rendering differently than their templates render when viewed outside the application.

Custom JS Interop Wrappers for DOM Elements and Web Components

The Errai Tutorial demonstrates how you can integrate web components with your Errai app, and how you can write your own custom element wrappers with specialized data-binding behaviour.

The tutorial now uses the Polymer paper-input and paper-textarea web components as part of a @Templated form. These components can be injected and used as @DataFields (as they are here). By using Errai's new HasValue interface for native @JsTypes with the @JsProperty annotation, these wrappers declaratively instruct Errai to use the "value" property of the paper elements for data-binding.

The tutorial also includes custom anchor element wrappers that showcase more complex data-binding behaviour. The BindableEmailAnchor is a wrapper for an anchor element that uses HasValue and @JsOverlay so that @Bound instances will display an email address as a mailto link as well as in the anchor text content.

Since the @JsOverlay method implementation is the only code generated by the GWT-compiler for a native @JsType, this is a light-weight way to declare element interfaces with custom data-binding behaviour.

Uses JQuery to Demonstrate Third-Party JavaScript Integration

The Errai Tutorial has a wrapper for a small subset of JQuery to showcase third-party JavaScript integration. With only a single @Produces annotation added to the JQuery wrapper, it is possible to inject the JQuery function for use in GWT code.

In general, we on the Errai team believe that using dependency injection is a best practice, but this is especially important with native JavaScript objects. By injecting the JQuery function rather than accessing it through a static method, it is much easier to mock out that object and test the code using it in a Java SE environment.

Try It Out and Give Us Your Feedback

We encourage you all to check out Errai 4.0.0.Beta4 and our new tutorial and share with us your feedback, whether that feedback is bug reports to our JIRA page, or more general disucssion in our forum.

Until the next time, happy coding!

Friday, September 30, 2016

Errai 4.0.0.Beta3 released!


Today we have the pleasure of announcing a new Errai release, 4.0.0.Beta3. Some important highlights in this release are:
  • GWT version upgraded to 2.8.0-rc2.
  • support for different merging strategies on @DataField attributes.
  • support for JS interop DOM event wrappers for @EventHandler methods.
Without any delay, let's talk about what these changes mean for you.

GWT Version Upgrade to 2.8.0-rc2

If you tried using Errai 4.0.0.Beta2 with GWT 2.8 snapshots or 2.8.0-rc2 you may have experienced issues running Super Dev Mode because of transitive dependency conflicts between GWT and Errai. These issues are resolved in 4.0.0.Beta3.

Data-Field Attribute Merging Strategies

When Errai initialises a templated bean, it merges attributes of data-fields in the HTML file with attributes on @DataFields in the @Templated Java file. In previous versions, attribute values of the data-fields in the HTML file always overrode @DataField attribute values. For example, for the Errai template below, the value of the title attribute at runtime would be "template".

As of this release, you can select between two strategies: USE_BEAN and USE_TEMPLATE.

Merging Single-Valued Attributes

For most attributes, USE_TEMPLATE (the default) causes merging to happen as in previous Errai versions: attribute values on a data-fields in the HTML file will override values of the respective @DataFields.

Conversely, the USE_BEAN strategy will preserve attribute values from the @DataField, only copying attribute values from a data-field in the HTML template if that attribute is not set in the respective @DataField.

You can declare which strategies to use as part of the @DataField annotation, with the ability to specify strategies for specific attributes, or a default strategy for all other attributes. In the example below, the "title" attribute will keep whatever value is set on the @DataField and all other attributes will have the value from the template data-field.

Merging List-Valued Attributes

Both strategies behave a bit differently when merging the "style" and "class" attributes because these attributes have list values.

When merging class values, all class names from the template and Java field are preserved. In other words, all CSS classes are combined between template data-fields and Java @DataFields regardless of which strategy is selected.

For example, below the "container" div will have the following classes (even if a different merging strategy was specified on the @DataField): "template bean both"

When merging style properties, individual CSS rules are kept from both the Java @DataField and the template data-fields as long as they do not conflict with each other. When there is a conflict, the selected strategy is used to resolve it, where USE_TEMPLATE causes the HTML data-field style value to win, and USE_BEAN causes the Java @DataField value to win.

In the example below, the "container" div will have the following style after the merging strategy is applied: "color: red; font-weight: bold; background-color: black"

JS Interop DOM Event Wrappers

In this release we have introduced a @BrowserEvent annotation for defining a native @JsType as an interface for a DOM Event. Annotated types can be used with the @EventHandler annotation to define methods as event listeners similarly to how @EventHandler is used with GWT Widget events. Several @BrowserEvent interfaces can be found in errai-common, covering the more common DOM event interfaces.

Below is an excerpt from the MouseEvent interface in errai-common.

Unlike GWT Widget events, multiple kinds of DOM events can share the same interface. The @BrowserEvent value for MouseEvent specifies the names of DOM events for which MouseEvent is an interface.

Because of this many-to-one mapping, declaring a handler method with a @BrowserEvent works similarly to declaring a native GWT event. There is a new @ForEvent annotation that is used to specify for which DOM event a handler should listen (which is analogous to @SinkNative for native GWT events).

An @EventHandler with a @BrowserEvent type can be registered for any data-field in the template HTML file, whether or not it has a corresponding @DataField in the Java bean.

Next Steps

Keep an eye out for upcoming blog posts focusing on some of the more advanced new features in Errai 4 such as JS interop support.

Until then, happy coding!

Friday, July 1, 2016

Errai 4.0.0.Beta2 released!


Today we're happy to announce the release of Errai 4.0.0.Beta2. This release includes lots of little fixes and enhancements including:
  • The EmbeddedWildflyLauncher for Super Dev Mode has been upgraded to use WildFly 10
  • Errai Navigation has new annotations for linking native anchors to Errai Navigation pages
  • Improved code-generation performance
  • Better support for declarative data-binding to native DOM elements
  • An injectable ManagedInstance for dynamically creating bean instances that manages the instances' life-cycles
Below we'll explain what some of these changes mean before talking about next steps.

WildFly 10 Upgrade

The EmbeddedWildflyLauncher now support WidFly 10+. Because of API changes in WildFly, it was not possible to maintain backwards compatibility with WildFly 8. That means that you have two options when upgrading Errai to 4.0.0.Beta2.

Upgrading to WildFly 10 (Recommended)

If you use the same WildFly configuration shown in the Errai Tutorial then you need only upgrade the as.version property to 10.0.0.Final. If you have any other configuration, just make sure that the errai.jboss.home system property in your Super Dev Mode configuration points to the root of a WildFly 10 installation.

Don't Upgrade errai-cdi-jboss

If you can't migrate to WildFly 10 right away, you can use an older version of errai-cdi-jboss (which contains the launcher) while still using the newest beta release for all other Errai jars.

Errai Navigation Links with Native Anchors

Errai Navigation has two new annotations that you can use on native Anchors for linking to Errai Navigation pages:
  • org.jboss.errai.ui.nav.client.local.api.TransitionTo
  • org.jboss.errai.ui.nav.client.local.api.TransitionToRole

These annotations are meant to replace the widget-based TransitionAnchor. Below we show them used in an Errai UI templated bean.

The first anchor links directly to the FAQPage while the second links to the page with the DefaultPage role. As with the previous transition anchors, Anchors with TransitionTo or TransitionToRole are validated at compile-time.

Better Data-Binding Support for Native DOM Elements

There were two issues with declarative data-binding of native elements in Errai 4.0.0.Beta1:
  • @Bound on a native element would fail in some cases for beans that were not @Templated
  • @Bound(onKeyUp=true) on an input element (TextInput, NumberInput, etc.) was not supported (and would cause compilation errors)
Both of these issues are fixed in 4.0.0.Beta2, moving Errai two small steps closer to the goal of GWT widget-free UI development.

Creating Beans Dynamically with Managed Life-Cycles

Errai supports CDI's Instance<T> for dynamically creating bean instances, but this API has some practical issues:
  • An instance created by an Instance<T> is managed by the caller. The caller is responsible for destroying the bean, which can lead to memory leaks.
  • Calling destroy on an Instance<T> destroys a bean regardless of its scope. But usually it is only desirable to destroy @Dependent beans, since @ApplicationScoped beans tend to be used throughout the entire runtime of an application.
Errai 4.0.0.Beta2 includes a new ManagedInstance<T> interface with similar methods but slightly different semantics that aim to simplify dynamic bean creation:
  • The destroy method on ManagedInstance<T> destroys @Dependent instances and is a no-op for all other scopes.
  • ManagedInstance<T> has a destroyAll method that destroys all @Dependent instances created by it.
  • When a ManagedInstance<T> is destroyed, its destroyAll method is called. A ManagedInstance<T> is destroyed when the bean it is injected into is destroyed.
In case the significance of that last point isn't immediately clear, this means that every dynamically created @Dependent instance from ManagedInstance<T> is cleaned-up when the type that injected that ManagedInstance<T> is destroyed. This avoids memory leaks and boiler-plate in short-lived components that create dynamic instances (like lists of UI elements).

Next Steps

In the coming weeks here are some of the features and tasks we will be working on:
In the interim, please try out Errai 4.0.0.Beta2 and tell us what you think.

Happy coding!

Friday, April 1, 2016

Errai 4.0.0.Beta1 released!

Greetings everyone!

As we write this, GWT and Errai are 10- and 6-years-old projects respectively. In those years, the web development community has progressed at an amazing speed, which has led some to ask the question: Is there still a place for these projects now and in the future?

We on the Errai Team continue to see huge value in our type-safe and declarative programming model for developing large projects. It is because of this value that we continue to actively develop Errai and it is because of this value that we continue to say this.

Today we're happy to announce the release of Errai 4.0.0.Beta1, targeting GWT 2.8.0-Beta1. This release brings exciting new features for working with native JavaScript and HTML, as well as improved refresh times in Super Dev Mode. In particular, 4.0.0.Beta1 includes:

  • A new Errai IoC container supporting partial code regeneration for improved refresh performance in Super Dev Mode
  • Greater compliance with CDI such as:
  • Support for injecting native JavaScript objects into IoC beans with JS interop
  • Support for injecting Errai IoC beans across separately compiled GWT scripts
  • Support for native DOM-based UI development with:
    • JS interop wrappers for common DOM elements
    • A declarative way of defining custom element wrappers available for injection in Errai IoC
    • Ability to use native DOM elements with Errai UI @DataFields, Errai Navigation @Pages, and Errai Data Binding @Bound fields

So what do all these changes mean for you?

Performance Improvements

When developing in Super Dev Mode, refreshing after modifying an IoC managed type requires generating significantly less code, decreasing the overall refresh time.
At runtime, applications with many @ApplicationScoped beans will notice decreased start-up times as @ApplicationScoped beans are now lazily instantiated by default.

Templated Beans with Native HTML Elements

In Errai 4 it's now possible to develop UI components without Widgets, and instead with thin-wrappers around native HTML elements. Here is a @Templated bean for a form using Errai UI and Data Binding.

How is this different from Errai 3?
  • Div, TextInput, and TextArea are not Widgets. Rather they are thin-wrappers around the div, input, and textarea elements respectively (using the GWT 2.8 JS Interop API)
  • The ContactForm does not extend Composite
  • The root element of the template is accessible as a @DataField. (This can be used to manually add this template to the DOM.)

Injecting Other DOM Elements

Errai 4 provides built-in thin-wrappers for most commonly used HTML elements, which you can you use in place of Widgets. The complete collection can be found in this package.
In case you wish to inject elements which do not have specific wrappers provided by Errai, you may use either of the following options.

Use the @Named Qualifier

Using the @Named qualifier, it is possible to inject an HTMLElement with any tag name. For example, here is how you could inject a nav element.

Create your own @Element

It's also very simple to declare your own thin DOM wrappers using the new @Element annotation. For example, here is a thin wrapper for the nav element that, if included in your project, can be available for injection in the IoC.

Next Steps

For those of you itching to learn more, our next blog post will take a deep dive into native JavaScript support in Errai 4, including how you can make arbitrary JavaScript objects injectable and how you can inject Errai IoC beans across separately compiled GWT scripts.
Until then you can check out our new and improved Errai Tutorial, which showcases all of the features mentioned here.

Happy coding!