I must find somewhere for my collected knowledge on the “joy” of using Sencha themebuilder. At my company, we’re currently working on building a custom style for our web application. Somewhere in the past, the decision was made to use Sencha GXT for their custom widgets and styling on top of GWT. Like most frameworks, things went smoothly as long as we were using the functionality out of the box. However, when we tried venturing outside, we were quickly reprimanded by the limitations of the framework.
In our scenario, we needed to brand our application differently than one of the built-in Sencha themes. Fortunately for us, or so we thought, Sencha created a nice tool in the knick-of-time called the “themebuilder” (currently in beta as of 2/25/2014). The themebuilder alleviates some pains of styling if you stay strictly within the guardrails, but quickly becomes inadequate if you need to do styling on top of it.
Part A: About the themebuilder and running it.
-
Running it is easy (just make sure you are using java version 1.7+). On a mac:
- You run ./themer.sh with certain command line options. The themer script reads in a custom Sencha file (*.theme) which it then uses to compile and build a set of appearance classes which GWT accepts. Here’s an example of the command I used:
- ./themer.sh ../examples/mytheme/mytheme.theme
- The .theme file is a huge pain to work with. It’s Sencha’s own proprietary format. It’s currently not well documented, which makes it very difficult to know how certain values within the .theme file map to Sencha widgets and how these get mapped on top of GWT and then what eventually gets spat out in your browser. Here’s a snippet:
theme { /* First, create a name for your theme, and define a package to place it in */ name = "myCustomTheme" basePackage = "com.example" /* Next, configure these basic defaults, to be used throughout the file */ text = util.fontStyle("Arial, Helvetica, sans-serif", "12px", "#000000", "normal") textWhite = util.fontStyle("Arial, Helvetica, sans-serif", "12px", "#eeeeee", "normal") borderRadius = 6 bgColor = "#ffffff" headerBgColor = "#666666" menuHoverColor = "#e7e7e7" menuSelectColor = "#b7daff" headerBgColorLight = "#f9f9f9" iconColor = "#777777" ... }You can see that the file is not quite json, java, or css. It’s some mishmash of everything, but it allows you to define variables and reference them later on in the .theme. This is Sencha’s claim for the themebuilders utility. By simply changing a few values (e.g. the background color, font color, font text, etc.), you can change the entire look and feel of your web application. That is all fine and dandy, but what is not described is what things you actually can and can’t change. For example, here’s a list of things I found that the themebuilder is not capable of:
- Styling a widget in one instance different from another
- Adding custom fonts
- Styling nested widgets differently from non-nested widget (e.g. a button in one panel looking different than a button in another)
- Support for icons libraries like font-awesome or glyphicon
- Styling text within a toolbar (the LabelToolItem widget)
- Styling the body content various content panels widgets (ContentPanel, FramedPanel, AccordionPanelAppearance, Window, Dialog)
- Stylizing a button when its menu is open vs. closed
In the next series of posts, I’ll be showing you how I solved each of these issues. Stay tuned for more.
A general tip: When modifying the .theme file, I used sublime text and had the syntax set to “Javascript.” This enabled some basic coloring and recognition of comments and strings. The coloring was very helpful.
Part B: Applying the custom theme on top of your GWT project
This part is more specific to GWT users, but may be helpful to some. I’m currently working in a build environment using Java 1.7, Eclipse Version: Kepler Service Release 1, Build id: 20130919-0819, GWT plugin version 1.8.9 to Eclipse, and maven. Assuming that you’re already configured and up and running with GXT and GWT, you should have an App.gwt.xml file that looks something like this:<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE module PUBLIC "-//Google Inc.//DTD Google Web Toolkit 2.5.1//EN" "http://google-web-toolkit.googlecode.com/svn/tags/2.5.1/distro-source/core/src/gwt-module.dtd"> <module rename-to='mymodule'> ... <!-- GXT Theme --> <inherits name='com.example.Theme' /> ... </module>
The key line is the GXT Theme line where GWT applies a theme on top of all of its widgets. This theme name should follow the convention set forth in your .theme file.
name = "myCustomTheme" basePackage = "com.example"
After you build your theme.jar file using the custom .theme file (I used the skeleton.theme file included which has all the values in it), you need to add the jar to your buildpath (or to maven as a dependency). I found that the fastest workflow for me was to modify the .theme file, use an html tool that Sencha includes to approximate the styles, and have my buildpath point directly to the .jar file where it’s created by the themebuilder. For more on this html tool (which helps speed up theme creation), see this post.
Edit: The new beta themebuilder (released by Sencha on 2/25/2014) spits out some instructions on how to do this, along with the context name of your theme.jar file.
Here’s a sample:
The customTheme theme has finished generating. Copy the jar (/path/to/theme/customTheme.jar) into your project and copy the following line into your gwt.xml file: <inherits name="com.example.Theme" />Then, I run GWT Server through my eclipse in debug mode, which picks up the changes to the theme. Because GWT is trying to rapidly render and compile all of the javascript files and apply the custom theme, it tends to operate very slowly.
Hopefully if everything went according to play, you should see a different style on top of your application. In the next posts, I’ll start getting into customizing the theme and some workarounds for its deficiencies.
As of the beta 2/25/2014, the running the themer will by default override the .jar file.
Code and Codes 