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