GWT/GXT Theming Part 2 – Adding Custom Appearance Classes on top of Sencha Themebuilder

Likely one of the first things you’ll encounter if using the themebuilder is how to create a custom style for something the themebuilder doesn’t support. In my adventures trying to build on top of Sencha’s themebuilder, it became apparent to me that they intended the tool to be used in a standalone fashion. That is, one runs the or themer.bat file to generate the theme.jar file and you plug and play it in conjunction with GWT.

However, because the theme file is applied uniformly across your application, what happens if you don’t want buttons in one place to look like buttons in another? This came up when building our webapp, where we wanted our top-level nav to have one color and appearance on hover and other buttons within the application to have another color. As it turns out, there’s no way to specify this in the .theme file.

  • One set of buttons (rendered by the themebuilder)
  • Screen Shot 2014-02-27 at 2.25.46 PM

  • Another set of buttons (custom appearance)
  • Screen Shot 2014-02-27 at 2.29.29 PM

  • Yet another set of buttons (customer appearance)
  • Screen Shot 2014-02-27 at 2.30.20 PM

    So how did I do this? In fact, there isn’t an easy way currently. I had to go digging through the compiled appearance classes made by the themebuilder.jar file in search of an answer. Here’s an example of what the themebuilder spits out for a button made with your custom .theme file.

    Step 1: Create an custom appearance class for your button/widget that extends Sencha’s appearance class

    So the first step I found to creating custom styling on top of the themebuilder was to create my own appearance class. However, I didn’t want to start from scratch because Sencha already provides a good basis (e.g. by applying the fonts, default colors, creating sliced image files, etc). It’s true that a lot of these things go out of the window when creating your own appearance class and you can lose multi-browser support, but in our case, it was better than keeping all the buttons looking exactly the same.

    Here’s example of a custom appearance class for the dark grey buttons you see above.

     * HeaderButtonAppearance extends a theme appearance created by Sencha's
     * themebuilder.jar file.  It uses the gifs and base css created by Sencha's
     * themebuilder then adds additional css styling and modifies the rendering
     * logic to display header buttons.  
    public class HeaderButtonAppearance<M> extends ButtonCellDefaultAppearance<M> {
      	final HeaderButtonStyle customStyle;
    	 * These are "resources" that comprise a ButtonCellAppearance
    	 * This interface describes the resources used by this button appearance.  This is not 
    	 * Sencha-specific.  I had originally tried extending the Css3ButtonResources class that 
             * the themebuilder spits out, but it required keeping the entire .css class in my package as well.
      	public interface HeaderButtonResources extends ClientBundle {
      		HeaderButtonStyle style();
            //These methods are my new styles.
      	public interface HeaderButtonStyle extends CssResource {
      		String headerButton();
      		String outerButton();
      	public HeaderButtonAppearance() {
      		HeaderButtonResources headerResources = GWT.create(HeaderButtonResources.class);
      		customStyle =;
      		StyleInjectorHelper.ensureInjected(, true);
        public void render(ButtonCell<M> cell, Context context, M value, SafeHtmlBuilder sb) {
      	    Css3ButtonResources resources = GWT.create(Css3ButtonResources.class);
      	    Css3ButtonStyle style =;
                //Additional rendering stuff here, use style.____() to access the custom themebuilder styles
                //Sencha by default uses a two nested divs to render a button.  You may have to extract the precise
                //.class file from the theme.jar file to see how the html is constructed.
      There are a few quirks regarding this appearance class to be aware of:

    • In the *ButtonStyle interface, the string method maps to a css class name in the *ButtonResources interface css file.
    • The .css file that is used for the mapping must be in the same package as the appearance class
    • In order to use the styles made available through the compiled css and appearance classes built by the themebuilder, you have to instantiate a ClientBundle and access the css classes through the Css3ButtonStyle interface.
    • Because the default rendering of the button renders the themebuilder’s classes (e.g. for buttons, there are two nested divs, where the outer has .button {} applied and the inner has .buttonInner {} applied, I had to rewrite the render method myself. In my replacement, I swapped out the .button and .buttonInner classes for my own css classes. I maintain everything else.
    • I think there has to be a better way to do this. For example, I experimented with injecting html (an innermost div) into the cell which accepts only my css. That way, I could avoid having to @Override the render class and modify the html on the backend. However, it didn’t end up working very well because even with injecting my own css, I could not overwrite the styling applied to the parent divs. Ultimately, I think one could write a utility to go in and scrape out the other classes applied by the themebuilder, but this seemed like it would be a real hassle.

    Step 2: Define the .css classes in a file in the same package for your custom appearance

    Here’s an example of what my .css class looked like.

    .outerButton {
      border: none;
      background-color: #3892D3;
      background: transparent;
      padding: 4px;
      cursor: pointer;
      outline: none;
    .headerButton {
      	padding: 0px;
      	text-align: left;
    	font-family: Arial, Helvetica, sans-serif;  /* actual font is not arial */
    	font-size: 17px;
    .headerButton:hover {
    	color: white;

    If you look at my HeaderButtonStyle class, you’ll notice that the css class names map directly to the functions in the interface. GWT takes care of the actual mapping of values. These are the classes that I can use to style my widget and are accessible via my instance of the HeaderButtonStyle. Here’s an example of how I render the HeaderStyleButton:

        public void render(ButtonCell<M> cell, Context context, M value, SafeHtmlBuilder sb) {
                //The default style CSS Resource in case I need to access styles built by the themebuilder
      	    Css3ButtonResources resources = GWT.create(Css3ButtonResources.class);
      	    Css3ButtonStyle style =;
                //Begin actual construction of the button widget
      	    String constantHtml = cell.getHTML();
      	    boolean hasConstantHtml = constantHtml != null && constantHtml.length() != 0;
      	    boolean isBoolean = value != null && value instanceof Boolean;
      	    String text = hasConstantHtml ? cell.getText() : (value != null && !isBoolean)
      	        ? SafeHtmlUtils.htmlEscape(value.toString()) : "";
      	    String scaleClass = "";
      	    String iconClass = "";
      	    String additionalCssClasses = customStyle.headerButton();
                //Size-dependent styling
      	    ButtonScale scale = cell.getScale();
      	    switch (scale) {
      	      case SMALL:
      	        scaleClass = style.small();
      	      case MEDIUM:
      	        scaleClass = style.medium();
      	      case LARGE:
      	        scaleClass = style.large();
                //Outer button class, you could add anything else you want here
      	    String buttonClass = customStyle.outerButton();
      	    boolean hasText = text != null && !text.equals("");
      	    if (!hasText) {
      	      buttonClass += " " + style.noText();
                //The css classes applied to the inner div
                String innerClass = "";
      	    innerClass += " " + scaleClass;
      	    innerClass += " " + additionalCssClasses;
      	    SafeHtmlBuilder builder = new SafeHtmlBuilder();
      	    builder.appendHtmlConstant("<div class='" + buttonClass + "'>");
      	    builder.appendHtmlConstant("<div class='" + innerClass + "'>");

    Step 3: Instantiate your widget using your custom appearance.

    TextButton button = new TextButton(new TextButtonCell(
            			new HeaderButtonAppearance<String>()), "Text for Button");

    You can see that when I instantiate a button, I pass in an appearance class instantiated with the type of value that the button receives (a string in this case). If you look at the prebuilt java classes (e.g. Css3ButtonCellAppearance) from the themebuilder, you’ll notice that the default constructor with no parameters will instantiate a cell with the default appearance. That’s why it’s necessary to use the constructor where you pass in the actual custom appearance class.


    Adding css sprites in GWT on top of GXT 3.1

    I’m a GWT/GXT beginner, so I typically end up having to look up how to do every little thing online in terms of styling/theming. However, after looking online for how to add css sprites to my application on top of GWT/GXT, I couldn’t find a good guide explaining how to do this. So I investigated and tinkered on my own and thought I would share what I discovered. There are a few necessary components:

    Step 1: Define your ClientBundle

    //My resource interface 
    public interface MyResources extends ClientBundle {
        @ImageOptions(repeatStyle = RepeatStyle.None)
        ImageResource my_sprites();
        MyCssResource resource();
        interface MyCssResource extends CssResource { 
        	String myLogo();
        	String anotherSprite();

    Here’s what my sprite image looks like: example

    First, it’s necessary to define an interface that extends the GWT ClientBundle. This interface becomes the entry point to injecting the proper CSS sprite into your web application.

    In the source above, you can see that I have a .png (this has to be in the same package as the interface), which is your sprite image. The way sprites are loaded are through a css class, which is defined in the CssResource which is also a part of the interface. You use the @Source annotations to define what the names of your files are.

    Here’s an example of what the css file should look like: You’ll notice that the gwt-image maps onto the name of the ImageResource method that is your css sprite. The height and width css properties correspond to the chunk of the image to use as your sprite. Background-position corresponds to where to start in the image (pixels from top, pixels from left).

    /* mysprites.css */
    @sprite .myLogo {
      gwt-image: "my_sprites";
      width: 86px;
      height: 36px;
      background-position: 0 0;
    @sprite .anotherSprite {
      gwt-image: "my_sprites";
      width: 86px;
      height: 36px;
      background-position: 36 0;

    Next, you define the interface of your CssResource, whose methods (String methodName();) get mapped to css classes defined in your css file.

    Step 2: Get an instance of your ClientBundle using GWT.create

    //My widget class
    private static MyResources myresource = GWT.create(MyResources.class);

    This is the instance that you will use to add sprites to your widget. I was doing this for a while, but noticed that after trying to call the methods made available through my CssResource interface, the css class was not being injected into my application. However, I did find that my sprite image was correctly injected. After some more online research, I found that you need to call this in order to ensure that the css class is actually injected. Add this line after you instantiate the class in order to actually put your css classes in your application

    //My widget class

    Here, myresource is the GWT object created for the entire resources class. resources() is the CSSResource which has the method ensureInjected(); Finally, you need to actually add a widget that contains the correctly styling in order to render the sprite correctly. Since CSS sprites are just classes, I used a blank GWT HTML widget, which just gets rendered as a blank div in your application.

    Step 3: Add the sprite to your application

    //My widget class
    HTML logo = new HTML();		
    mybanner.add(logo, new HorizontalLayoutData(-1, -1, new Margins(0, 5, 5, 5)));

    Finally, in your application if you inspect the element, you can see that the CSS class got rendered into the application and attached to the HTML widget


    /* Inspected Javascript */
    .GKTGO20BA3B-MyResources-MyCssResource-myLogo {
    height: 492px;
    width: 68px;
    overflow: hidden;
    background: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEQAAAHsCAYAAABrKwuFAAAPFUlE…Als9kMoqN9zlNMpAqDBOKWCBBGJ4BCICgySCoQhAEzbD+D1IzkMByojJyAAAAAElFTkSuQmCC") -0px -0px no-repeat;
    width: 68px;
    height: 36px;
    background-position: 0 0;

    The end result:

    Screen Shot 2014-02-26 at 12.24.31 PM
    Let me know if you have any comments or questions.