Creating a theme using SASS

In Vaadin 7 you set the theme in use by specifying the @Theme annotation on your UI, e.g @Theme(“themename”). Ignoring Sass for a second, you would then create a mytheme/styles.css that typically @import the Reindeer theme (in case you forgot, your theme should be located in WebContent/VAADIN/themes/<themename>/styles.css). You can start using Sass with this approach, by renaming your styles.css to styles.scss and importing legacy-styles.css instead of styles.css - the resulting CSS will be exactly as the same as before, BUT now you’re free to use Sass in your theme:

Here we just define a Sass variable to use as color for button captions.

NOTE that this way (using legacy-styles) you still lose one important new feature: you can’t have multiple themes on the same page when using the legacy-styles.css -approach. To gain this feature, which is crucial if you intend to run multiple applications with different themes embedded in the same page (e.g portals), you must use Sass.

Provided you’re in development mode (not production), the scss will automatically be translated into CSS. You can also compile the scss manually (and MUST do so for production). To do this you should run com.vaadin.sass.SassCompiler with the Vaadin jars on the classpath and give it your scss file and output file as arguments. If you have the jars readily available, you could do something like this in the command line:

Another way would be to save the auto-compiled styles.css from the browser.

Support has been added to the Eclipse plugin through the Compile Vaadin Theme button .

NOTE that if you’re using Ivy (the default if you’re using the Eclipse plugin), you must make sure to get the appropriate dependencies on your classpath some other way (since they are not present in WEB-INF/lib). In Eclipse, use the Run -dialog to inherit the classpath from your project.

You’ll notice that the resulting theme still uses @import to 'extend' the Reindeer theme:

This approach is an easy way to get started with Sass, but will cause two requests (one for our theme, one for Reindeer). Let’s have a look at the recommended approach next.

Instead of using CSS @import to base your application theme on, you can (and probably should) use Sass @import to make a monolithic theme (one CSS file, one request when using the application). Just @import reindeer.scss, and @include it:

This produces a styles.css that contains all the styles for Reindeer as well as your custom styles (note that this makes your final CSS quite big to scroll trough, so you might not want to do this when just learning the Sass syntax). There is no @import in the compiled CSS, so it will not cause additional requests. Additionally, due to the way Vaadin Sass is structured, this opens up for many possibilities to customize, mix-and-match themes, and leave unused stuff out.

One important thing to notice, is that we wrapped everything in .themename {}, in this case .mytheme {}. This is the magic sauce that makes it possible to have multiple themes on one page. It is crucial that the name matches your themename, or your styles will not be applied.

Some of the nice features you get with Sass include variables, selector nesting, mixins (optionally with parameters), selector inheritance. For more information of what you can do with Sass, you should refer to the official documentation at http://sass-lang.com

Please note that the Vaadin Sass compiler only supports the “SCSS”, which is the “new main syntax” (the original Sass also supports another, older syntax).The Vaadin version aims to be completely compatible, though initially there will be some limitations (and actually some added functionality). Please let us know if you find something is not working as expected.

In Vaadin 7, all Vaadin core themes are using Sass. The reindeer/styles.css we included first, is the compiled Reindeer theme, including the stuff from the Base theme that Reindeer extends. The Sass for the Reindeer theme is in reindeer/reindeer.scss, and contains one big mixin that will include the whole theme, unless you specifically tell it to leave out some parts. The themes are further divided into smaller parts, that can be left out, or separately included and renamed - providing a powerful way to customize and mix-and-match themes.

It is recommended that you go ahead an divide your own theme into at least two files as well: styles.scss and themename.scss (where 'themename' is the name of your theme). This is will make your theme extendable, and also has the nice benefit that file you usually edit is uniquely named (themename.scss) instead of a generic styles.scss that you might have many of.

For a theme named 'mytheme', this would look as follows:

mytheme/styles.scss:

mytheme/mytheme.scss:

This is the exact structure Vaadin core themes are using, and the way the Eclipse plugin will set things up for you (not yet in beta 10).

Of course, you’re still free to arrange your theme in another way if you prefer.

Upcoming tutorials will address specific use-cases!