From 1d1aba6c26e82a19fc5941b254f60f905f818e8e Mon Sep 17 00:00:00 2001 From: Erik Lumme Date: Wed, 13 Sep 2017 10:18:04 +0300 Subject: [PATCH] Migrate CreatingAThemeUsingSass --- .../articles/CreatingAThemeUsingSass.asciidoc | 195 ++++++++++++++++++ documentation/articles/contents.asciidoc | 1 + 2 files changed, 196 insertions(+) create mode 100644 documentation/articles/CreatingAThemeUsingSass.asciidoc diff --git a/documentation/articles/CreatingAThemeUsingSass.asciidoc b/documentation/articles/CreatingAThemeUsingSass.asciidoc new file mode 100644 index 0000000000..6b0b519325 --- /dev/null +++ b/documentation/articles/CreatingAThemeUsingSass.asciidoc @@ -0,0 +1,195 @@ +[[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//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 paramaters), 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! diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc index dfff4e427b..1351a07c0b 100644 --- a/documentation/articles/contents.asciidoc +++ b/documentation/articles/contents.asciidoc @@ -64,3 +64,4 @@ are great, too. - link:ValoExamples.asciidoc[Valo examples] - link:ReadOnlyVsDisabledFields.asciidoc[Read-only vs Disabled fields] - link:CreatingAUIExtension.asciidoc[Creating a UI extension] +- link:CreatingAThemeUsingSass.asciidoc[Creating a theme using Sass] -- 2.39.5