123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200 |
- ---
- title: Creating A Theme Using SASS
- order: 78
- layout: page
- ---
-
- [[creating-a-theme-using-sass]]
- = Creating a theme using SASS
-
- Vaadin 7 comes with built in support for Sass, which can be thought of
- as a preprocessor for CSS. From the Sass homepage:
-
- _Sass makes CSS fun again. Sass is an extension of CSS3, adding nested
- rules, variables, mixins, selector inheritance, and more._
-
- Sass looks like CSS with some added features, and is compiled into CSS
- before being sent to the browser. The compilation is either done
- beforehand, or (during development) on-the-fly by the servlet.
-
- In Vaadin 7 you can make use of Sass in any of your CSS, and as usual
- there are more than one way to arrange this. The recommended way if you
- do not have a specific reason not to do so, is to compile your theme
- into one CSS file (that is: without any CSS @include), but we'll start
- with the getting-your-feet-wet approach that looks exactly as
- before.It’s worth noting that you can continue to use CSS without Sass
- just as before, if you prefer.
-
- [[getting-your-feet-wet]]
- Getting your feet wet
- ^^^^^^^^^^^^^^^^^^^^^
-
- 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:
-
- [source,scss]
- ....
- @import url(../reindeer/legacy-styles.css);
- $color : green;
- .v-button-caption {
- color: $color;
- }
- ....
-
- 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.
-
- [[compiling]]
- Compiling
- ^^^^^^^^^
-
- 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:
-
- [source,bash]
- ....
- > java -cp '../../../WEB-INF/lib/*' com.vaadin.sass.SassCompiler styles.scss styles.css
- ....
-
- 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:
-
- [source,scss]
- ....
- @import url(../reindeer/legacy-styles.css);
- ....
-
- 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.
-
- [[going-deeper]]
- Going deeper
- ^^^^^^^^^^^^
-
- 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:
-
- [source,scss]
- ....
- // mytheme.scss
- @import "../reindeer/reindeer.scss";
-
- .mytheme {
- @include reindeer;
-
- $color : yellow;
- .v-button-caption {
- color: $color;
- }
- }
- ....
-
- 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.
-
- [[one-more-thing-recommended-structure]]
- One more thing: Recommended structure
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
- 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:`
-
- [source,scss]
- ....
- @import "mytheme.scss";
- .mytheme {
- @include mytheme;
- }
- ....
-
- `mytheme/mytheme.scss`:
-
- [source,scss]
- ....
- @import "../reindeer/reindeer.scss";
-
- @mixin mytheme {
-
- // your styles go here
-
- @include reindeer;
- }
- ....
-
- 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!
|