GWT Theo : GSS variables, theme file, icons and style guide made easy

So say you have a beautiful GWT application that uses GSS. Smart developer that you are, you did this using a theme file to easily manage your variables, in order to speed up your coding and ensure visual consistency across your screens. Now it’s time to automate things with GWT Theo!

GWT Theo is my adaptation of the powerful Theo set of Gulp plugins to automate theme creation. It has been stripped down a lot and tweaked to meet the specifics requirement of GWT. It will create your Java classes for each set of variables (fonts, colors, sizes, …) and your unique theme file, regrouping all those elements. It will also generate a style guide based on your variables for quick reference . Last but not least, it will facilitate custom icon integration (currently only supporting icon sets from Icomoon).

There’s a repository with a working project available on Github and a live application just here. Have a look at the style guide, you will fall in love! This blog post walks you through how to use GWT Theo.

Importing GWT Theo to your project

Let’s start by cloning the GWT Theo repository at the root of your application (at the same level of your src repository).

git clone https://github.com/ArcBees/gwt-theo.git

You will then need to update the gulpfile.js in order to match your application’s paths. On Arcbees’ website, it would look like this :

Once it’s done, you can give it a try and run gulp in your terminal in the GWT Theo folder. You will need Gulp installed on your computer. Default files should be generated inside folders specified in your gulpfile.js. The default Colors.java file will look like this :

Using the generated theme file

Once your files have been generated, you can bind the theme with your GSS files. All you need to do is to locate a GSS file you’d like to power-up with your theme, making it possible to use your custom variables inside of it, and providing the theme.gss in it’s source.

In my case, my source declaration for my style.gss file is in my AppResources.java file. Don’t forget to require the theme in your GSS file, and that’s it! You can now use all of your variables :

Custom variables

By default, GWT Theo comes with 3 files for variables : colors, fonts and sizes, located inside the theme-properties folder. You can add more, of course, or remove anything that you won’t need. Variables are declared in a JSON file with a default structure looking like this :

  • global [object] : Definition for this set of variables
    • type [string] : The variable type (this will influence the layout of the style guide)
      • color [option for type] : Used for colors
      • size [option for type] : Used for string variables
    • category [string] : Defines the category, and creates a section in the style guide
    • classname [string] : The class name for the file that will be generated from this set of variables
    • title [string] : ?
  • props : Definition of your variables
    • title-* [object, optional] : Everything starting with “title-” will be converted into a title in the style guide. Must be unique (“title-foo”, “title-bar”).
      • value [string] : Your title
    • * [object] : The name of your variable
      • value [string] : The value of the defined variable
      • comment [string, optional] : For variable of size type, a comment about that variable

Adding or removing a set of variables

Variables files are loaded from the theme.json file. You can remove or add a new set from here.

Custom icons

Using custom icons in your application is fun, but can be a real pain with GWT. You need to declare a lot of stuff in order to make it work. GWT Theo can help you with that, but it currently supports only one way of doing it.

Generating everything

  1. Select icons from Icomoon. These can be predefined icons from various packs available on Icomoon, or you can create your own by uploading svg files.
  2. Once you have made your choices, generate your font (bottom right).
  3. Before downloading the package, open the Preferences (top left) and :
    1. Rename the font name to “icons”
    2. Rename the class prefix to “icon_”
  4. Download the package.
  5. Extract it.
  6. Inside of your GWT Theo folder, create an theme-files folder and paste your extracted icons folder into it.
  7. Now, inside GWT Theo’s gulpfile.js, after the gwt variable (around line 29), add this one, and don’t forget to update the path to match your application :

If you run gulp now, it will create the required ThemeResources.java and icons.gss files :

Using custom icons in a view

To use your custom icon set in a view for the first time, you will need to inject it into your Resource Loader :

You can now use it in any of your views :

In a project that is always evolving, where you add adding new custom fonts often, this process will save you a lot of time! New icons to add? Generate a new font, dump it into the theme-files folder, gulp it, and voilà!

The style guide

GWT Theo will also create a style guide for you. You can define it’s path in the gulpfile.js. The default path is src/main/webapp/_theme-guide, which means that you can access it from your application at : your-application-url/_theme-guide/index.html.

The style guide will help your team quickly see predefined variables for your GSS files, and it will also help them spot the icons that they can use, if you have added some.

Conclusion

GWT Theo is still a work in progress and a lot could be added. Nevertheless, it already has the ability to save you precious time. Never forget that these kinds of tools should suit your own workflow and development needs, so feel free to tweak GWT Theo as much as required!