Migrate CreatingAThemeUsingSass

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/<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 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!

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]