When to use GWT ensureInjected()?

Question

I created a few styles into a CSSResource and it works well whether I use

GWT.<MyResources>create(MyResources.class).myStyles().ensureInjected();

or not.

Could anyone shed a light on this and explain when to use ensureInjected or not?

Thank you! Daniel

Answer 1

As Christian said, inside the UiBinder ui.xml file you don't have to worry about invoking ensureInjected(), the following XML statements do the job:

<ui:with field='myStyle' type='com...MyStyle'/>

<div class='{myStyle.redBorder}'/>

Of course this is assuming that there is somewhere a MyStyle interface defined:

public interface MyStyle {
    public String redBorder();
}

Now I agree with you that things get annoying when you need to manipulate the CssResource extension outside of UiBinder templates. Precisely because you have to take care of invoking ensureInjected() somewhere before using the MyStyle instance with your widgets.

I personally use GIN to inject instances of extensions of CssResource whenever I need them.That way you can implement a custom GIN provider ensuring that ensureInjected() is called on the CssResource before injecting it. There are three steps involved there:

• Create an interface for MyStyle alongside with a CSS file.
  MyStyle.java

  public interface MyStyle {
      public String redBorder();
  }
  

• MyStyle.css

  .redBorder { border: 1px solid red; }
  

• Expose it through a ClientBundle extension.
  Resources.java

  public interface Resources extends ClientBundle {
      @Source("MyStyle.css")
      public MyStyle style();
  }
  

• Configure a GIN provider method to inject your instances of MyStyle.
  ClientModule.java

  public class ClientModule extends AbstractGinModule {
      @Override
      protected void configure() {
      //...
      }
  
      @Provides MyStyle createStyle(final Resources resources) {
          MyStyle style = resources.style();
          style.ensureInjected();
          return style;
      }
  }
  

We smoothly inject the Resources instance here above, which means no more hassle of a static accessor calling GWT.<Resources>create(Resources.class) anywhere, it just all happens through the GIN injection.

Having done that you can inject your instances of MyStyle when you need them.
For example (in some MVP context):

private Widget widget;

@Inject
public SomeView(final MyStyle style) {
    //...
    widget = uiBinder.createAndBindUi(this);
    widget.addStyleName(style.redBorder());
}

Answer 2

The rule is easy: you have to call ensureInjected() explicitly, unless the CssResource is being generated from an <ui:style> in a UiBinder template (because most of the time you won't have a handle on the generated CssResource.
Specifically, <ui:with> provides no special treatment for CssResources.

Also, a few widgets take a specific ClientBundle as argument to a constructor (such as CellTable), they will then call ensureInjected() on the CssResource they use.

Answer 3

Good question - one situation that comes to my mind is when you want to use styles from some global stylesheet in a UiBinder template - then you need to call ensureInjected to... ensure the styles are indeed injected when you are referencing them (the "local" UiBinder styles, that you define in xml are automagically injected).

You can see this used as such in the Mail example:

public void onModuleLoad() {
    // Inject global styles.
    GWT.<GlobalResources>create(GlobalResources.class).css().ensureInjected();

    // Create the UI defined in Mail.ui.xml.
    DockLayoutPanel outer = binder.createAndBindUi(this);

    // ...rest of the code
}

Note how ensureInjected is called before binding the UI.

This is the only situation I know that warrants using ensureInjected, but maybe I missed something.

Answer 4

If you use UiBinder the call to ensureInjected is provided by the tag ui:with. For any other css you are using in a client bundle (i.e. legacy css excluded) and that are not declared in a ui:with block, you have to call ensureInjected explicitly.