From 99d6de546c74f0eed230ea8253dda6b85109d2e7 Mon Sep 17 00:00:00 2001 From: Markus Koivisto Date: Fri, 22 Jan 2016 14:55:18 +0200 Subject: Add documentation to master branch Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674 --- documentation/themes/chapter-themes.asciidoc | 37 + .../themes/img/addon-responsive-flexwrap.png | Bin 0 -> 117149 bytes documentation/themes/img/builtin-runo.png | Bin 0 -> 9705 bytes .../themes/img/eclipse-theme-compiler.png | Bin 0 -> 10979 bytes .../img/eclipse-theme-created-annotated-hi.png | Bin 0 -> 69642 bytes .../img/eclipse-theme-created-annotated-lo.png | Bin 0 -> 33779 bytes documentation/themes/img/eclipse-theme-created.png | Bin 0 -> 69951 bytes documentation/themes/img/eclipse-theme-new.png | Bin 0 -> 28613 bytes .../themes/img/eclipse-theme-settings.png | Bin 0 -> 23459 bytes documentation/themes/img/example-ui-default.png | Bin 0 -> 88842 bytes documentation/themes/img/example-ui-themed.png | Bin 0 -> 23719 bytes documentation/themes/img/fonticons-basic.png | Bin 0 -> 4783 bytes documentation/themes/img/fonticons-html.png | Bin 0 -> 3765 bytes documentation/themes/img/theme-contents-hi.png | Bin 0 -> 289363 bytes documentation/themes/img/theme-contents-lo.png | Bin 0 -> 74403 bytes documentation/themes/img/themes-css-match-1.png | Bin 0 -> 4983 bytes .../themes/img/themes-css-match-class-2.png | Bin 0 -> 10131 bytes .../themes/img/themes-css-match-class-3.png | Bin 0 -> 8873 bytes .../eclipse-theme-created-annotated.svg | 144 ++ .../themes/original-drawings/theme-contents.svg | 1857 ++++++++++++++++++++ documentation/themes/themes-compiling.asciidoc | 223 +++ documentation/themes/themes-creating.asciidoc | 283 +++ documentation/themes/themes-css.asciidoc | 506 ++++++ documentation/themes/themes-eclipse.asciidoc | 75 + documentation/themes/themes-fonticon.asciidoc | 266 +++ documentation/themes/themes-fonts.asciidoc | 85 + documentation/themes/themes-overview.asciidoc | 77 + documentation/themes/themes-responsive.asciidoc | 286 +++ documentation/themes/themes-sass.asciidoc | 156 ++ documentation/themes/themes-valo.asciidoc | 440 +++++ 30 files changed, 4435 insertions(+) create mode 100644 documentation/themes/chapter-themes.asciidoc create mode 100644 documentation/themes/img/addon-responsive-flexwrap.png create mode 100644 documentation/themes/img/builtin-runo.png create mode 100644 documentation/themes/img/eclipse-theme-compiler.png create mode 100644 documentation/themes/img/eclipse-theme-created-annotated-hi.png create mode 100644 documentation/themes/img/eclipse-theme-created-annotated-lo.png create mode 100644 documentation/themes/img/eclipse-theme-created.png create mode 100644 documentation/themes/img/eclipse-theme-new.png create mode 100644 documentation/themes/img/eclipse-theme-settings.png create mode 100644 documentation/themes/img/example-ui-default.png create mode 100644 documentation/themes/img/example-ui-themed.png create mode 100644 documentation/themes/img/fonticons-basic.png create mode 100644 documentation/themes/img/fonticons-html.png create mode 100644 documentation/themes/img/theme-contents-hi.png create mode 100644 documentation/themes/img/theme-contents-lo.png create mode 100644 documentation/themes/img/themes-css-match-1.png create mode 100644 documentation/themes/img/themes-css-match-class-2.png create mode 100644 documentation/themes/img/themes-css-match-class-3.png create mode 100644 documentation/themes/original-drawings/eclipse-theme-created-annotated.svg create mode 100644 documentation/themes/original-drawings/theme-contents.svg create mode 100644 documentation/themes/themes-compiling.asciidoc create mode 100644 documentation/themes/themes-creating.asciidoc create mode 100644 documentation/themes/themes-css.asciidoc create mode 100644 documentation/themes/themes-eclipse.asciidoc create mode 100644 documentation/themes/themes-fonticon.asciidoc create mode 100644 documentation/themes/themes-fonts.asciidoc create mode 100644 documentation/themes/themes-overview.asciidoc create mode 100644 documentation/themes/themes-responsive.asciidoc create mode 100644 documentation/themes/themes-sass.asciidoc create mode 100644 documentation/themes/themes-valo.asciidoc (limited to 'documentation/themes') diff --git a/documentation/themes/chapter-themes.asciidoc b/documentation/themes/chapter-themes.asciidoc new file mode 100644 index 0000000000..727e42b3e9 --- /dev/null +++ b/documentation/themes/chapter-themes.asciidoc @@ -0,0 +1,37 @@ +[[themes]] +== Themes + +((("theme", id="term.themes", range="startofrange"))) + + +((("CSS", id="term.themes-css", range="startofrange"))) + + +This chapter provides details about using and creating __themes__ that control +the visual look of web applications. Themes are created using Sass, which is an +extension of CSS (Cascading Style Sheets), or with plain CSS. We provide an +introduction to CSS, especially concerning the styling of HTML by element +classes. + + +include::themes-overview.asciidoc[leveloffset=+2] + +include::themes-css.asciidoc[leveloffset=+2] + +include::themes-sass.asciidoc[leveloffset=+2] + +include::themes-compiling.asciidoc[leveloffset=+2] + +include::themes-creating.asciidoc[leveloffset=+2] + +include::themes-eclipse.asciidoc[leveloffset=+2] + +include::themes-valo.asciidoc[leveloffset=+2] + +include::themes-fonticon.asciidoc[leveloffset=+2] + +include::themes-fonts.asciidoc[leveloffset=+2] + +include::themes-responsive.asciidoc[leveloffset=+2] +(((range="endofrange", startref="term.themes"))) +(((range="endofrange", startref="term.themes-css"))) diff --git a/documentation/themes/img/addon-responsive-flexwrap.png b/documentation/themes/img/addon-responsive-flexwrap.png new file mode 100644 index 0000000000..e24df04a47 Binary files /dev/null and b/documentation/themes/img/addon-responsive-flexwrap.png differ diff --git a/documentation/themes/img/builtin-runo.png b/documentation/themes/img/builtin-runo.png new file mode 100644 index 0000000000..039a34137b Binary files /dev/null and b/documentation/themes/img/builtin-runo.png differ diff --git a/documentation/themes/img/eclipse-theme-compiler.png b/documentation/themes/img/eclipse-theme-compiler.png new file mode 100644 index 0000000000..a2886a4e68 Binary files /dev/null and b/documentation/themes/img/eclipse-theme-compiler.png differ diff --git a/documentation/themes/img/eclipse-theme-created-annotated-hi.png b/documentation/themes/img/eclipse-theme-created-annotated-hi.png new file mode 100644 index 0000000000..de8152c2da Binary files /dev/null and b/documentation/themes/img/eclipse-theme-created-annotated-hi.png differ diff --git a/documentation/themes/img/eclipse-theme-created-annotated-lo.png b/documentation/themes/img/eclipse-theme-created-annotated-lo.png new file mode 100644 index 0000000000..fe9fa560d7 Binary files /dev/null and b/documentation/themes/img/eclipse-theme-created-annotated-lo.png differ diff --git a/documentation/themes/img/eclipse-theme-created.png b/documentation/themes/img/eclipse-theme-created.png new file mode 100644 index 0000000000..db1970a461 Binary files /dev/null and b/documentation/themes/img/eclipse-theme-created.png differ diff --git a/documentation/themes/img/eclipse-theme-new.png b/documentation/themes/img/eclipse-theme-new.png new file mode 100644 index 0000000000..9374364298 Binary files /dev/null and b/documentation/themes/img/eclipse-theme-new.png differ diff --git a/documentation/themes/img/eclipse-theme-settings.png b/documentation/themes/img/eclipse-theme-settings.png new file mode 100644 index 0000000000..a7dfd78721 Binary files /dev/null and b/documentation/themes/img/eclipse-theme-settings.png differ diff --git a/documentation/themes/img/example-ui-default.png b/documentation/themes/img/example-ui-default.png new file mode 100644 index 0000000000..a0e9f9d1ea Binary files /dev/null and b/documentation/themes/img/example-ui-default.png differ diff --git a/documentation/themes/img/example-ui-themed.png b/documentation/themes/img/example-ui-themed.png new file mode 100644 index 0000000000..40ebb746cc Binary files /dev/null and b/documentation/themes/img/example-ui-themed.png differ diff --git a/documentation/themes/img/fonticons-basic.png b/documentation/themes/img/fonticons-basic.png new file mode 100644 index 0000000000..66ed207cf7 Binary files /dev/null and b/documentation/themes/img/fonticons-basic.png differ diff --git a/documentation/themes/img/fonticons-html.png b/documentation/themes/img/fonticons-html.png new file mode 100644 index 0000000000..b9d8a2a9c6 Binary files /dev/null and b/documentation/themes/img/fonticons-html.png differ diff --git a/documentation/themes/img/theme-contents-hi.png b/documentation/themes/img/theme-contents-hi.png new file mode 100644 index 0000000000..d04f7b2d32 Binary files /dev/null and b/documentation/themes/img/theme-contents-hi.png differ diff --git a/documentation/themes/img/theme-contents-lo.png b/documentation/themes/img/theme-contents-lo.png new file mode 100644 index 0000000000..cef64982e8 Binary files /dev/null and b/documentation/themes/img/theme-contents-lo.png differ diff --git a/documentation/themes/img/themes-css-match-1.png b/documentation/themes/img/themes-css-match-1.png new file mode 100644 index 0000000000..8f9cf1bd55 Binary files /dev/null and b/documentation/themes/img/themes-css-match-1.png differ diff --git a/documentation/themes/img/themes-css-match-class-2.png b/documentation/themes/img/themes-css-match-class-2.png new file mode 100644 index 0000000000..c1cab59bf9 Binary files /dev/null and b/documentation/themes/img/themes-css-match-class-2.png differ diff --git a/documentation/themes/img/themes-css-match-class-3.png b/documentation/themes/img/themes-css-match-class-3.png new file mode 100644 index 0000000000..7062b9abdb Binary files /dev/null and b/documentation/themes/img/themes-css-match-class-3.png differ diff --git a/documentation/themes/original-drawings/eclipse-theme-created-annotated.svg b/documentation/themes/original-drawings/eclipse-theme-created-annotated.svg new file mode 100644 index 0000000000..f6b902f45d --- /dev/null +++ b/documentation/themes/original-drawings/eclipse-theme-created-annotated.svg @@ -0,0 +1,144 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/documentation/themes/original-drawings/theme-contents.svg b/documentation/themes/original-drawings/theme-contents.svg new file mode 100644 index 0000000000..169336beba --- /dev/null +++ b/documentation/themes/original-drawings/theme-contents.svg @@ -0,0 +1,1857 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + mytheme.scss mytheme img myimage.png layouts mylayout.html VAADIN/themes - a custom theme - actual Sass style sheet - image resources - custom layouts - layout template valo.scss valo - a built-in theme - theme Sass style sheet + + + + + + @import "../valo/valo"; styles.scss - theme main Sass style sheet + @import "mytheme.scss"; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + addons.scss - autogenerated addon theme inclusions + + + + + + diff --git a/documentation/themes/themes-compiling.asciidoc b/documentation/themes/themes-compiling.asciidoc new file mode 100644 index 0000000000..7c8501858a --- /dev/null +++ b/documentation/themes/themes-compiling.asciidoc @@ -0,0 +1,223 @@ +--- +title: Compiling Sass Themes +order: 4 +layout: page +--- + +[[themes.compiling]] += Compiling Sass Themes + +Sass themes must be compiled to CSS understood by browsers. Compilation can be +done with the Vaadin Sass Compiler, which you can run in Eclipse, Maven, or it +can be run on-the-fly when the application is loaded in the browser. You can +also use any other Sass compiler. + +[[themes.compiling.on-the-fly]] +== Compiling On the Fly + +The easiest way to use Sass themes during theme development is to let the Vaadin +servlet compile them on the run. In this case, the SCSS source files are placed +in the theme folder. Compilation is done each time the [filename]#styles.css# is +requested from the server. + +The on-the-fly compilation takes a bit time, so it is only available when the +Vaadin servlet is in the development mode, as described in +<>. Also, it requires the theme compiler and +all its dependencies to be in the class path of the servlet. At least for +production, you must compile the theme to CSS, as described next. + + +[[themes.compiling.eclipse]] +== Compiling in Eclipse + +If using Eclipse and the Vaadin Plugin for Eclipse, its project wizard creates a +Sass theme. It includes [menuchoice]#Compile Theme# command in the toolbar to +compile the project theme to CSS. Another command compiles also the widget set. + +[[figure.themes.compiling.eclipse]] +.Compiling Sass Theme +image::img/eclipse-theme-compiler.png[] + +The [filename]#WebContent/VAADIN/mytheme/styles.scss# and any Sass sources +included by it are compiled to [filename]#styles.css#. + + +[[themes.compiling.maven]] +== Compiling with Maven + +To compile the themes with Maven, you need to include the built-in themes as a +dependency: + + +[source, xml] +---- + ... + + ... + + com.vaadin + vaadin-themes + ${vaadin.version} + + + ... +---- + +This is automatically included at least in the +[literal]#++vaadin-archetype-application++# archetype for Vaadin applications. +The actual theme compilation is most conveniently done by the Vaadin Maven +Plugin with [literal]#++update-theme++# and [literal]#++compile-theme++# goals. + + +[source, xml] +---- + ... + + com.vaadin + vaadin-maven-plugin + ... + + + ... + + clean + resources + update-theme + update-widgetset + compile-theme + compile + + + +---- + +Once these are in place, the theme is compiled as part of relevant lifecycle +phases, such as [literal]#++package++#. + +[subs="normal"] +---- +[command]#mvn# [parameter]#package# +---- +You can also compile just the theme with the [package]#compile-theme# goal: + +[subs="normal"] +---- +[command]#mvn# [parameter]#vaadin:compile-theme# +---- + +ifdef::web[] +[[themes.compiling.command-line]] +== Compiling in Command-line + +You can compile Sass style sheets to CSS either with the Vaadin Sass compiler or +the standard one. The [filename]#styles.css# of a custom theme should be the +compilation target. When compiled before deployment, the source files do not +need to be in the theme folder. + +You can run the Vaadin Sass compiler in a theme folder as follows: + +[subs="normal"] +---- +[command]#java# [parameter]#-cp# [replaceable]#'../../../WEB-INF/lib/*'# com.vaadin.sass.SassCompiler styles.scss styles.css +---- +The [parameter]#-cp# parameter should point to the class path where the Vaadin +Sass Compiler and theme JARs are located. In the above example, they are assumed +to be located in the [filename]#WEB-INF/lib# folder of the web application. If +you have loaded the Vaadin libraries using Ivy, as is the case with projects +created with the Vaadin Plugin for Eclipse, the Vaadin libraries are stored in +Ivy's local repository. Its folder hierarchy is somewhat scattered, so we +recommend that you retrieve the libraries to a single folder. We recommend using +an Ant script as is described next. + +endif::web[] + +[[themes.compiling.ant]] +== Compiling with Ant + +With Apache Ant, you can easily resolve the dependencies with Ivy and compile +the theme with the Theme Compiler included in Vaadin as follows. This build step +can be conveniently included in a WAR build script. + +Start with the following configuration: + + +[source, xml] +---- + + + + + + + ... other project build definitions ... + + + + + + + + + + + + + + + + + + + + + + + +---- + +You should first resolve all Vaadin libraries to a single directory, which you +can use for deployment, but also for theme compilation. + + +---- + + + +---- + +Then, you can compile the theme as follows: + + +---- + + + + + + + + + + + + + + + + + + + + + +---- + + + + diff --git a/documentation/themes/themes-creating.asciidoc b/documentation/themes/themes-creating.asciidoc new file mode 100644 index 0000000000..dcd2c5034a --- /dev/null +++ b/documentation/themes/themes-creating.asciidoc @@ -0,0 +1,283 @@ +--- +title: Creating and Using Themes +order: 5 +layout: page +--- + +[[themes.creating]] += Creating and Using Themes + +Custom themes are placed in the [filename]#VAADIN/themes# folder of the web +application, in an Eclipse project under the [filename]#WebContent# folder or +[filename]#src/main/webapp# in Maven projects, as was illustrated in +<>. This location is fixed. You need to have a theme folder for each +theme you use in your application, although applications rarely need more than a +single theme. + +[[themes.creating.sass]] +== Sass Themes + +You can use Sass themes in Vaadin in two ways, either by compiling them to CSS +by yourself or by letting the Vaadin servlet compile them for you on-the-fly +when the theme CSS is requested by the browser, as described in +<>. + +To define a Sass theme with the name mytheme, you must place a file with name +[filename]#styles.scss# in the theme folder [filename]#VAADIN/themes/mytheme#. +If no [filename]#styles.css# exists in the folder, the Sass file is compiled +on-the-fly when the theme is requested by a browser. + +We recommend that you organize the theme in at least two SCSS files so that you +import the actual theme from a Sass file that is named more uniquely than the +[filename]#styles.scss#, to make it distinquishable in the editor. This +organization is how the Vaadin Plugin for Eclipse creates a new theme. + +If you use Vaadin add-ons that contain themes, Vaadin Plugin for Eclipse and +Maven automatically add them to the [filename]#addons.scss# file. + +[[themes.creating.sass.scss]] +=== Theme SCSS + +We recommend that the rules in a theme should be prefixed with a selector for +the theme name. You can do the prefixing in Sass by enclosing the rules in a +nested rule with a selector for the theme name. + +Themes are defined as Sass mixins, so after you import the mixin definitions, +you can [literal]#++@include++# them in the theme rule as follows: + + +[source, css] +---- +@import "addons.scss"; +@import "mytheme.scss"; + +.mytheme { + @include addons; + @include mytheme; +} +---- + +However, this is mainly necessary if you use the UI in portlets, each of which +can have its own theme, or in the special circumstance that the theme has rules +that use empty parent selector [literal]#++&++# to refer to the theme name. + +Otherwise, you can safely leave the nested theme selector out as follows: + + +[source, css] +---- +@import "addons.scss"; +@import "mytheme.scss"; + +@include addons; +@include mytheme; +---- + +The actual theme should be defined as follows, as a mixin that includes the base +theme. + + +[source, css] +---- +@import "../valo/valo.scss"; + +@mixin mytheme { + @include valo; + + /* An actual theme rule */ + .v-button { + color: blue; + } +} + +---- + + +[[themes.creating.sass.addons]] +=== Add-on Themes + +Some Vaadin add-ons include Sass styles that need to be compiled into the theme. +These are managed in the [filename]#addons.scss# file in a theme, included from +the [filename]#styles.scss#. The [filename]#addons.scss# file is automatically +generated by the Vaadin Plugin for Eclipse or Maven. + +[subs="normal"] +---- +/* This file is automatically managed and will be + overwritten from time to time. */ +/* Do not manually edit this file. */ + +**/++*++ Provided by vaadin-spreadsheet-1.0.0.beta1.jar ++*++/ @import "../../../VAADIN/addons/spreadsheet/spreadsheet.scss";** + +/* Import and include this mixin into your project + theme to include the addon themes */ +@mixin addons { + **@include spreadsheet;** +} +---- + + +[[themes.creating.css]] +== Plain Old CSS Themes + +In addition to Sass themes, you can create plain old CSS themes. CSS theme are +more restricted than Sass styles - you can't parameterize CSS themes in any way, +unlike you can Valo, for example. Further, an application can only have one CSS +theme while you can have multiple Sass themes. + +A CSS theme is defined in a [filename]#styles.css# file in the +[filename]#VAADIN/themes/mytheme# folder. You need to import the +[filename]#legacy-styles.css# of the built-in theme as follows: + + +---- +@import "../reindeer/legacy-styles.css"; + +.v-app { + background: yellow; +} +---- + + +[[themes.creating.standard-components]] +== Styling Standard Components + +Each user interface component in Vaadin has a CSS style class that you can use +to control the appearance of the component. Many components have additional +sub-elements that also allow styling. You can add context-specific stylenames +with [methodname]#addStyleName()#. Notice that [methodname]#getStyleName()# +returns only the custom stylenames, not the built-in stylenames for the +component. + +Please see the section on each component for a description of its styles. Most +of the stylenames are determined in the client-side widget of each component. +The easiest way to find out the styles of the elements is to use a HTML +inspector such as +FireBug.//// +TODO reference to a Firebug section when +available +//// + +Some client-side components or component styles can be shared by different +server-side components. For example, [literal]#++v-textfield++# style is used +for all text input boxes in components, in addition to [classname]#TextField#. + + +[[themes.creating.builtin]] +== Built-in Themes + +Vaadin currently includes the following built-in themes: + +* [literal]#++valo++#, the primary theme since Vaadin 7.3 +* [literal]#++reindeer++#, the primary theme in Vaadin 6 and 7 +* [literal]#++chameleon++#, an easily customizable theme +* [literal]#++runo++#, the default theme in IT Mill Toolkit 5 +* [literal]#++liferay++#, for Liferay portlets + +In addition, there is the [literal]#++base++# theme, which should not be used +directly, but is extended by the other built-in themes, except valo. + +The built-in themes are provided in the respective +[filename]#VAADIN/themes/<theme>/styles.scss# stylesheets in the +[filename]#vaadin-themes# JAR. Also the precompiled CSS files are included, in +case you want to use the themes directly. + +Various constants related to the built-in themes are defined in the theme +classes in [package]#com.vaadin.ui.themes# package. These are mostly special +style names for specific components. + + +---- +@Theme("runo") +public class MyUI extends UI { + @Override + protected void init(VaadinRequest request) { + ... + Panel panel = new Panel("Regular Panel in the Runo Theme"); + panel.addComponent(new Button("Regular Runo Button")); + + // A button with the "small" style + Button smallButton = new Button("Small Runo Button"); + smallButton.addStyleName(Runo.BUTTON_SMALL); + + Panel lightPanel = new Panel("Light Panel"); + lightPanel.addStyleName(Runo.PANEL_LIGHT); + lightPanel.addComponent( + new Label("With addStyleName(\"light\")")); + ... +---- + +The example with the Runo theme is shown in +<>. + +[[figure.themes.creating.builtin.runo]] +.Runo Theme +image::img/builtin-runo.png[] + +The built-in themes come with a custom icon font, FontAwesome, which is used for +icons in the theme, and which you can use as font icons, as described in +<>. + +ifdef::web[] + +[NOTE] +.Serving Built-In Themes Statically +==== +The built-in themes included in the Vaadin library JAR are served dynamically +from the JAR by the servlet. Serving themes and widget sets statically by the +web server is more efficient. To do so, you need to extract the +[filename]#VAADIN/# directories from the JAR to the web content directory ( +[filename]#WebContent# in Eclipse or [filename]#src/main/webapp# in Maven +projects). + +[subs="normal"] +---- +[prompt]#$# [command]#cd# WebContent +---- +[subs="normal"] +---- +[prompt]#$# [command]#unzip# path-to/vaadin-server-7.x.x.jar 'VAADIN/*' +---- +[subs="normal"] +---- +[prompt]#$# [command]#unzip# path-to/vaadin-themes-7.x.x.jar 'VAADIN/*' +---- +[subs="normal"] +---- +[prompt]#$# [command]#unzip# path-to/vaadin-client-compiled-7.x.x.jar 'VAADIN/*' +---- +You can also serve static content from a front-end caching server, which reduces +the load of the application server. In portals, you install the themes globally +in the portal in similar way, as described in +<>. + +Just make sure to update the static content when you upgrade to a newer version +of Vaadin. + +==== + +endif::web[] + + +Creation of a default theme for custom GWT widgets is described in +<>. + + +[[themes.creating.addon]] +== Add-on Themes + +You can find more themes as add-ons from the +link:http://vaadin.com/directory[Vaadin Directory]. In addition, many component +add-ons contain a theme for the components they provide. + +The add-on themes need to be included in the project theme. Vaadin Plugin for +Eclipse and Maven automatically include them in the [filename]#addons.scss# file +in the project theme folder. It should be included by the project theme. + + + + diff --git a/documentation/themes/themes-css.asciidoc b/documentation/themes/themes-css.asciidoc new file mode 100644 index 0000000000..45229303dc --- /dev/null +++ b/documentation/themes/themes-css.asciidoc @@ -0,0 +1,506 @@ +--- +title: Introduction to Cascading Style Sheets +order: 2 +layout: page +--- + +[[themes.css]] += Introduction to Cascading Style Sheets + +((("CSS", "introduction", id="term.themes.css", range="startofrange"))) + + +Cascading Style Sheets or CSS is the basic technique to separate the appearance +of a web page from the content represented in HTML. In this section, we give an +introduction to CSS and look how they are relevant to software development with +Vaadin. + +As we can only give a short intruction in this book, we encourage you to refer +to the rich literature on CSS and the many resources available in the web. You +can find the authoratitative specifications of CSS standards from the +link:http://www.w3.org/Style/CSS/[W3C +website] +ifdef::web[] +and other literature, references, and tutorials from the +link:http://www.dmoz.org/Computers/Data_Formats/Style_Sheets/CSS/[Open Directory +Project page on CSS], as well as from other +sources +endif::web[] +. + +[[themes.css.basics]] +== Applying CSS to HTML + +Let us consider the following HTML document that contains various markup +elements for formatting text. Vaadin UIs work in essentially similar documents, +even though they use somewhat different elements to draw the user interface. + +[subs="normal"] +---- +<html> + <head> + <title>My Page</title> + <link rel="stylesheet" type="text/css" + href="mystylesheet.css"/> + </head> + <body> + **<p>**This is a paragraph**</p>** + **<p>**This is another paragraph**</p>** + <table> + <tr> + **<td>**This is a table cell**</td>** + **<td>**This is another table cell**</td>** + </tr> + </table> + </body> +</html> +---- +The HTML elements that will be styled later by matching CSS rules are emphasized +above. + +The [literal]#++++# element in the HTML header defines the used CSS +stylesheet. The definition is automatically generated by Vaadin in the HTML page +that loads the UI of the application. A stylesheet can also be embedded in the +HTML document itself, as is done when optimizing their loading in Vaadin +TouchKit, for example. + + +[[themes.css.basics]] +== Basic CSS Rules + +A stylesheet contains a set of __rules__ that can match the HTML elements in the +page. Each rule consists of one or more __selectors__, separated with commas, +and a __declaration block__ enclosed in curly braces. A declaration block +contains a list of __property__ statements. Each property has a label and a +value, separated with a colon. A property statement ends with a semicolon. + +Let us look at an example that matches certain elements in the simple HTML +document given in the previous section: + + +[source, css] +---- +p, td { + color: blue; +} + +td { + background: yellow; + font-weight: bold; +} +---- + +The [literal]#++p++# and [literal]#++td++# are element type selectors that match +with [literal]#++

++# and [literal]#++++# elements in HTML, respectively. +The first rule matches with both elements, while the second matches only with +[literal]#++++# elements. Let us assume that you have saved the above style +sheet with the name [filename]#mystylesheet.css# and consider the following HTML +file located in the same folder. + +[[figure.themes.basic.1]] +.Simple Styling by Element Type +image::img/themes-css-match-1.png[] + +[[themes.css.basics.inheritance]] +=== Style Inheritance in CSS + +CSS has __inheritance__ where contained elements inherit the properties of their +parent elements. For example, let us change the above example and define it +instead as follows: + + +[source, css] +---- +table { + color: blue; + background: yellow; +} +---- + +All elements contained in the [literal]#++++# element would have the same +properties. For example, the text in the contained [literal]#++
++# elements +would be in blue color. + + +[[themes.css.basics.element-types]] +=== HTML Element Types + +HTML has a number of element types, each of which accepts a specific set of +properties. The [literal]#++
++# elements are generic elements that can be +used to create almost any layout and formatting that can be created with a +specific HTML element type. Vaadin uses [literal]#++
++# elements +extensively to draw the UI, especially in layout components. + +((("Google Web Toolkit", +"themeing"))) +Matching elements by their type as shown above is, however, rarely if ever used +in style sheets for Vaadin applications. We used it above, because it is the +normal way in regular HTML documents that use the various HTML elements for +formatting text, but it is not applicable in Vaadin UIs that consist mostly of +[literal]#++
++# elements. Instead, you need to match by element class, as +described next. + + + +[[themes.css.matching-by-class]] +== Matching by Element Class + +Matching HTML elements by the __class__ attribute is the most common form of +matching in Vaadin stylesheets. It is also possible to match with the +__identifier__ of a unique HTML element. + +The class of an HTML element is defined with the [parameter]#class# attribute as +follows: + +[subs="normal"] +---- +<html> + <body> + **<p class="normal">**This is the first paragraph**</p>** + + **<p class="another">**This is the second paragraph**</p>** + + <table> + <tr> + **<td class="normal">**This is a table cell**</td>** + **<td class="another">**This is another table cell**</td>** + </tr> + </table> + </body> +</html> +---- +The class attributes of HTML elements can be matched in CSS rules with a +selector notation where the class name is written after a period following the +element name. This gives us full control of matching elements by their type and +class. + + +[source, css] +---- +p.normal {color: red;} +p.another {color: blue;} +td.normal {background: pink;} +td.another {background: yellow;} +---- + +The page would look as shown below: + +.Matching HTML Element Type and Class +image::img/themes-css-match-class-2.png[] + +We can also match solely by the class by using the universal selector +[literal]#++*++# for the element name, for example [literal]#++*.normal++#. The +universal selector can also be left out altogether so that we use just the class +name following the period, for example [literal]#++.normal++#. + + +[source, css] +---- +.normal { + color: red; +} + +.another { + blackground: yellow; +} +---- + +In this case, the rule will match with all elements of the same class regardless +of the element type. The result is shown in <>. This +example illustrates a technique to make style sheets compatible regardless of +the exact HTML element used in drawing a component. + +[[figure.themes.match.class]] +.Matching Only HTML Element Class +image::img/themes-css-match-class-3.png[] + +To ensure future compatibility, we recommend that you use only matching based on +the classes and __do not__ match for specific HTML element types in CSS rules, +because Vaadin may change the exact HTML implementation how components are drawn +in the future. For example, Vaadin earlier used [literal]#++
++# element to +draw [classname]#Button# components, but later it was changed to use the +special-purpose [literal]#++
++# elements. If we want to match only +the table cell, we could use the following selector: + + +[source, css] +---- +.mytable .mytext {color: blue;} +---- + +To match, a class listed in a rule does not have to be an immediate descendant +of the previous class, but just a descendant. For example, the selector " +[literal]#++.v-panel .v-button++#" would match all elements with class +[literal]#++.v-button++# somewhere inside an element with class +[literal]#++.v-panel++#. + + +[[themes.css.cascading]] +== Importance of Cascading + +CSS or Cascading Stylesheets are, as the name implies, about __cascading__ +stylesheets, which means applying the stylesheet rules according to their +origin, importance, scope, specifity, and order. + +For exact rules for cascading in CSS, see the section +link:http://www.w3.org/TR/css3-cascade/#cascading[Cascading] in the CSS +specification. + +[[themes.css.cascading.importance]] +=== Importance + +Declarations in CSS rules can be made override declarations with otherwise +higher priority by annotating them as [literal]#++!important++#. For example, an +inline style setting made in the [literal]#++style++# attribute of an HTML +element has a higher specificity than any rule in a CSS stylesheet. + + +[source, css] +---- +
... +---- + +You can override the higher specificity with the [literal]#++!important++# +annotation as follows: + + +[source, css] +---- +.v-button {height: 30px !important;} +---- + + +[[themes.css.cascading.specificity]] +=== Specificity + +A rule that specifies an element with selectors more closely overrides ones that +specify it less specifically. With respect to the element class selectors most +commonly used in Vaadin themes, the specificity is determined by the number of +class selectors in the selector. + + +[source, css] +---- +.v-button {} +.v-verticallayout .v-button {} +.v-app .v-verticallayout .v-button {} +---- + +In the above example, the last rule would have the highest specificity and would +match. + +As noted earlier, style declarations given in the style attribute of a HTML +element have higher specificity than declarations in a CSS rule, except if the +[literal]#++!important++# annotation is given. + +See the CSS3 link:http://www.w3.org/TR/selectors/#specificity[selectors module +specification] for details regarding how the specificity is computed. + + +[[themes.css.cascading.order]] +=== Order + +CSS rules given later have higher priority than ones given earlier. For example, +in the following, the latter rule overrides the former and the color will be +black: + + +[source, css] +---- +.v-button {color: white} +.v-button {color: black} +---- + +As specificity has a higher cascading priority than order, you could make the +first rule have higher priority by adding specificity as follows: + + +[source, css] +---- +.v-app .v-button {color: white} +.v-button {color: black} +---- + +The order is important to notice in certain cases, because Vaadin does not +guarantee the order in which CSS stylesheets are loaded in the browser, which +can in fact be random and result in very unexpected behavior. This is not +relevant for Sass stylesheets, which are compiled to a single stylesheet. For +plain CSS stylesheets, such as add-on or TouchKit stylesheets, the order can be +relevant. + + + +[[themes.css.hierarchy]] +== Style Class Hierarchy of a Vaadin UI + +Let us give a real case in a Vaadin UI by considering a simple Vaadin UI with a +label and a button inside a vertical layout: + + +[source, java] +---- +// UI has v-ui style class +@Theme("mytheme") +public class HelloWorld extends UI { + @Override + protected void init(VaadinRequest request) { + // VerticalLayout has v-verticallayout style + VerticalLayout content = new VerticalLayout(); + setContent(content); + + // Label has v-label style + content.addComponent(new Label("Hello World!")); + + // Button has v-button style + content.addComponent(new Button("Push Me!", + new Button.ClickListener() { + @Override + public void buttonClick(ClickEvent event) { + Notification.show("Pushed!"); + } + })); + } +} +---- + +The UI will look by default as shown in <>. +By using a HTML inspector such as Firebug, you can view the HTML tree and the +element classes and applied styles for each element. + +[[figure.themes.css.hierarchy.initial]] +.An Unthemed Vaadin UI +image::img/example-ui-default.png[] + +Now, let us look at the HTML element class structure of the UI, as we can see it +in the HTML inspector: + +[subs="normal"] +---- +<body class="**v-generated-body v-ff v-ff20 v-ff200 v-gecko v-lin**" + scroll="auto"> + <div id="bookexamplesvaadin7helloworld-447164942" + class="**v-app mytheme**"> + <div class="**v-ui v-scrollable**" + tabindex="1" style="height: 100%; width: 100%;"> + <div class="**v-loading-indicator first**" + style="position: absolute; display: none;"></div> + <div class="**v-verticallayout v-layout v-vertical v-widget v-has-width**" + style="width: 100%;"> + <div class="**v-slot**"> + <div class="**v-label v-widget v-has-width**" + style="width: 100%;">Hello World!</div> + </div> + <div class="**v-slot**"> + <div class="**v-button v-widget**" + tabindex="0" role="button"> + <span class="**v-button-wrap**"> + <span class="**v-button-caption**">Push Me!</span> + </span> + </div> + </div> + </div> + </div> + </div> + ... +<body> +---- +Now, consider the following theme where we set the colors and margins of various +elements. The theme is actually a Sass theme. + + +[source, css] +---- +@import "../valo/valo.scss"; + +@mixin mytheme { + @include valo; + + /* White background for the entire UI */ + .v-ui { + background: white; + } + + /* All labels have white text on black background */ + .v-label { + background: black; + color: white; + font-size: 24pt; + line-height: 24pt; + padding: 5px; + } + + /* All buttons have blue caption and some margin */ + .v-button { + margin: 10px; + + /* A nested selector to increase specificity */ + .v-button-caption { + color: blue; + } + } +} +---- + +The look has changed as shown in <>. + +[[figure.themes.css.hierarchy.themed]] +.Themed Vaadin UI +image::img/example-ui-themed.png[] + +An element can have multiple classes separated with a space. With multiple +classes, a CSS rule matches an element if any of the classes match. This feature +is used in many Vaadin components to allow matching based on the state of the +component. For example, when the mouse is over a [classname]#Link# component, +[literal]#++over++# class is added to the component. Most of such styling is a +feature of Google Web Toolkit. + + +[[themes.css.compatibility]] +== Notes on Compatibility + +((("CSS", "compatibility"))) +((("compatibility"))) +CSS is a standard continuously under development. It was first proposed in 1994. +The specification of CSS is maintained by the CSS Working Group of World Wide +Web Consortium (W3C). Versioned with backward-compatible "levels", CSS Level 1 +was published in 1996, Level 2 in 1998, and the ongoing development of CSS Level +3 started in 1998. CSS3 is divided into a number of separate modules, each +developed and progressing separately, and many of the modules are already Level +4. + +While the support for CSS has been universal in all graphical web browsers since +at least 1995, the support has been very incomplete at times and there still +exists an unfortunate number of incompatibilities between browsers. While we +have tried to take these incompatibilities into account in the built-in themes +in Vaadin, you need to consider them while developing your own themes. +Compatibility issues are detailed in various CSS handbooks. + + +(((range="endofrange", startref="term.themes.css"))) + + diff --git a/documentation/themes/themes-eclipse.asciidoc b/documentation/themes/themes-eclipse.asciidoc new file mode 100644 index 0000000000..bd35ce6fed --- /dev/null +++ b/documentation/themes/themes-eclipse.asciidoc @@ -0,0 +1,75 @@ +--- +title: Creating a Theme in Eclipse +order: 6 +layout: page +--- + +[[themes.eclipse]] += Creating a Theme in Eclipse + +The Eclipse plugin automatically creates a theme stub for new Vaadin projects. +It also includes a wizard for creating new custom themes. Do the following steps +to create a new theme. + +. Select "File > New > Other..." in the main menu or right-click the +[guilabel]#Project Explorer# and select "New > Other...". A window will open. + +. In the [guilabel]#Select a wizard# step, select the "Vaadin > Vaadin Theme" +wizard. + ++ +image::img/eclipse-theme-new.png[] + ++ +Click [guibutton]#Next# to proceed to the next step. + +. In the [guilabel]#Create a new Vaadin theme# step, you have the following +settings: + +[guilabel]#Project#(mandatory):: The project in which the theme should be created. + +[guilabel]#Theme name#(mandatory):: The theme name is used as the name of the theme folder and in a CSS tag +(prefixed with " [literal]#++v-theme-++#"), so it must be a proper identifier. +Only latin alphanumerics, underscore, and minus sign are allowed. + +[guilabel]#Modify application classes to use theme#(optional):: The setting allows the wizard to write a code statement that enables the theme +in the constructor of the selected application (UI) class(es). If you need to +control the theme with dynamic logic, you can leave the setting unchecked or +change the generated line later. + + + ++ +image::img/eclipse-theme-settings.png[] + ++ +Click [guibutton]#Finish# to create the theme. + + +The wizard creates the theme folder under the +[filename]#WebContent/VAADIN/themes# folder and the actual style sheet as +[filename]#mytheme.scss# and [filename]#styles.scss# files, as illustrated in +<>. + +[[figure.eclipse.theme.created]] +.Newly Created Theme +image::img/eclipse-theme-created-annotated-hi.png[] + +The created theme extends a built-in base theme with an [literal]#++@import++# +statement. See the explanation of theme inheritance in +<>. Notice that the [filename]#reindeer# theme is not located in +the [filename]#widgetsets# folder, but in the Vaadin JAR. See +<> for information for serving the built-in themes. + +If you selected a UI class or classes in the [guilabel]#Modify application +classes to use theme# in the theme wizard, the wizard will add the +[literal]#++@Theme++# annotation to the UI class. + +If you later rename the theme in Eclipse, notice that changing the name of the +folder will not automatically change the [literal]#++@Theme++# annotation. You +need to change such references to theme names in the calls manually. + + + diff --git a/documentation/themes/themes-fonticon.asciidoc b/documentation/themes/themes-fonticon.asciidoc new file mode 100644 index 0000000000..624220fa05 --- /dev/null +++ b/documentation/themes/themes-fonticon.asciidoc @@ -0,0 +1,266 @@ +--- +title: Font Icons +order: 8 +layout: page +--- + +[[themes.fonticon]] += Font Icons + +Font icons are icons included in a font. Fonts have many advantages over bitmap +images. Browsers are usually faster in rendering fonts than loading image files. +Web fonts are vector graphics, so they are scalable. As font icons are text +characters, you can define their color in CSS by the regular foreground color +property. + +[[themes.fonticon.enabling]] +== Loading Icon Fonts + +Vaadin currently comes with one custom icon font: FontAwesome. It is +automatically enabled in the Valo theme. For other themes, you need to include +it with the following line in your project theme, after importing the base +theme: + + +---- +@include fonticons; +---- + +If you use other icon fonts, as described in <>, and the +font is not loaded by a base theme, you need to load it with a +[literal]#++font++# mixin in Sass, as described in +<>. + + +[[themes.fonticon.using]] +== Basic Use + +Font icons are resources of type [classname]#FontIcon#, which implements the +[interfacename]#Resource# interface. You can use these special resources for +component icons and such, but not as embedded images, for example. + +Each icon has a Unicode codepoint, by which you can use it. Vaadin includes an +awesome icon font, [literal]#++FontAwesome++#, which comes with an enumeration +of all the icons included in the font. + +Most typically, you set a component icon as follows: + + +---- +TextField name = new TextField("Name"); +name.setIcon(FontAwesome.USER); +layout.addComponent(name); + +// Button allows specifying icon resource in constructor +Button ok = new Button("OK", FontAwesome.CHECK); +layout.addComponent(ok); +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.basic[on-line example, window="_blank"]. + +The result is illustrated in <>, with the color +styling described next. + +[[figure.themes.fonticon.using]] +.Basic Use of Font Icons +image::img/fonticons-basic.png[] + +[[themes.fonticon.using.css]] +=== Styling the Icons + +As font icons are regular text, you can specify their color with the +[literal]#++color++# attribute in CSS to specify the foreground text color. All +HTML elements that display icons in Vaadin have the [literal]#++v-icon++# style +name. + + +---- +.v-icon { + color: blue; +} +---- + +If you use the font icon resources in other ways, such as in an +[classname]#Image# component, the style name will be different. + + + +[[themes.fonticon.html]] +== Using Font icons in HTML + +You can use font icons in HTML code, such as in a [classname]#Label#, by +generating the HTML to display the icon with the [methodname]#getHtml()# method. + + +---- +Label label = new Label("I " + + FontAwesome.HEART.getHtml() + " Vaadin", + ContentMode.HTML); +label.addStyleName("redicon"); +layout.addComponent(label); +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"]. + +The HTML code has the [literal]#++v-icon++# style, which you can modify in CSS: + + +---- +.redicon .v-icon { + color: red; +} +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"]. + +The result is illustrated in <>, with the color +styling described next. + +[[figure.themes.fonticon.html]] +.Using Font Icons in Label +image::img/fonticons-html.png[] + +You could have set the font color in the label's HTML code as well, or for all +icons in the UI. + +You can easily use font icons in HTML code in other ways as well. You just need +to use the correct font family and then use the hex-formatted Unicode codepoint +for the icon. See for example the implementation of the [methodname]#getHtml()# +method in [classname]#FontAwesome#: + + +---- +@Override +public String getHtml() { + return "&#x" + + Integer.toHexString(codepoint) + ";"; +} +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"]. + + +[[themes.fonticon.anywhere]] +== Using Font Icons in Other Text + +You can include a font icon in any text by its Unicode codepoint, which you can +get with the [methodname]#getCodePoint()# method. In such case, however, you +need to use the same font for other text in the same string as well. The +FontAwesome provided in Vaadin includes a basic character set. + + +---- +TextField amount = new TextField("Amount (in " + + new String(Character.toChars( + FontAwesome.BTC.getCodepoint())) + + ")"); +amount.addStyleName("awesomecaption"); +layout.addComponent(amount); +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.intext[on-line example, window="_blank"]. + +You need to set the font family in CSS. + + +---- +.v-caption-awesomecaption .v-captiontext { + font-family: FontAwesome; +} +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.intext[on-line example, window="_blank"]. + + +[[themes.fonticon.custom]] +== Custom Font Icons + +You can easily use glyphs in existing fonts as icons, or create your own. + +[[themes.fonticon.custom.creating]] +=== Creating New Icon Fonts With IcoMoon + +You are free to use any of the many ways to create icons and embed them into +fonts. Here, we give basic instructions for using the +link:http://icomoon.io/app/[IcoMoon] service, where you can pick icons from a +large library of well-designed icons. + +Font Awesome is included in IcoMoon's selection of icon libraries. Note that the +codepoints of the icons are not fixed, so the [classname]#FontAwesome# enum is +not compatible with such custom icon fonts. + +After you have selected the icons that you want in your font, you can download +them in a ZIP package. The package contains the icons in multiple formats, +including WOFF, TTF, EOT, and SVG. Not all browsers support any one of them, so +all are needed to support all the common browsers. Extract the [filename]#fonts# +folder from the package to under your theme. + +See <> for instructions for loading a custom font. + + +ifdef::web[] +[[themes.fonticon.custom.implementing]] +=== Implementing FontIcon + +You can define a font icon for any font available in the browser by implementing +the [interfacename]#FontIcon# interface. The normal pattern for implementing it +is to implement an enumeration for all the symbols available in the font. See +the implementation of [classname]#FontAwesome# for more details. + +You need a FontIcon API for the icons. In the following, we define a font icon +using a normal sans-serif font built-in in the browser. + + +---- +// Font icon definition with a single symbol +public enum MyFontIcon implements FontIcon { + EURO(0x20AC); + + private int codepoint; + + MyFontIcon(int codepoint) { + this.codepoint = codepoint; + } + + @Override + public String getMIMEType() { + throw new UnsupportedOperationException( + FontIcon.class.getSimpleName() + + " should not be used where a MIME type is needed."); + } + + @Override + public String getFontFamily() { + return "sans-serif"; + } + + @Override + public int getCodepoint() { + return codepoint; + } + + @Override + public String getHtml() { + return "&#x" + + Integer.toHexString(codepoint) + ";"; + } +} +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.custom[on-line example, window="_blank"]. + +Then you can use it as usual: + + +---- +TextField name = new TextField("Amount"); +name.setIcon(MyFontIcon.EURO); +layout.addComponent(name); +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.custom[on-line example, window="_blank"]. + +You could make the implementation a class as well, instead of an enumeration, to +allow other ways to specify the icons. + +endif::web[] + + + + diff --git a/documentation/themes/themes-fonts.asciidoc b/documentation/themes/themes-fonts.asciidoc new file mode 100644 index 0000000000..741fb00a72 --- /dev/null +++ b/documentation/themes/themes-fonts.asciidoc @@ -0,0 +1,85 @@ +--- +title: Custom Fonts +order: 9 +layout: page +--- + +[[themes.fonts]] += Custom Fonts + +In addition to using the built-in fonts of the browser and the web fonts +included in the Vaadin themes, you can use custom web fonts. + +[[themes.fonts.loading]] +== Loading Local Fonts + +You can load locally served web fonts with the [literal]#++font++# mixin as +follows: + + +---- +@include font(MyFontFamily, + '../../mytheme/fonts/myfontfamily'); +---- + +The statement must be given in the [filename]#styles.scss# file __outside__ the +[literal]#++.mytheme {}++# block. + +The first parameter is the name of the font family, which is used to identify +the font. If the font family name contains spaces, you need to use single or +double quotes around the name. + +The second parameter is the base name of the font files without an extension, +including a relative path. Notice that the path is relative to the base theme, +where the mixin is defined, not the used theme. We recommend placing custom font +files under a [filename]#fonts# folder in a theme. + +Not all browsers support any single font file format, so the base name is +appended with [filename]#.ttf#, [filename]#.eot#, [filename]#.woff#, or +[filename]#.svg# suffix for the font file suitable for a user's browser. + + +[[themes.fonts.webfonts]] +== Loading Web Fonts + +You can load externally served web fonts such as Google Fonts simply by +specifying the loading stylesheet for the UI with the [classname]#@StyleSheet# +annotation. + +For example, to load the "Cabin Sketch" font from Google Fonts: + +[subs="normal"] +---- +@StyleSheet({"[replaceable]#http://fonts.googleapis.com/css?family=Cabin+Sketch#"}) +public class MyUI extends UI { + ... +---- +ifdef::web[] +Note that such web fonts served from a domain different from the Vaadin +application currently link:https://dev.vaadin.com/ticket/16249[do not work +together with] responsive themes, as described in +<>. The problem occurs only in Firefox. A SecurityError is shown in the +debug window. +endif::web[] + + +[[themes.fonts.using]] +== Using Custom Fonts + +After loaded, you can use a custom font, or actually font family, by its name in +CSS and otherwise. + + +---- +.mystyle { + font-family: MyFontFamily; +} +---- + +Again, if the font family name contains spaces, you need to use single or double +quotes around the name. + + + + diff --git a/documentation/themes/themes-overview.asciidoc b/documentation/themes/themes-overview.asciidoc new file mode 100644 index 0000000000..05005ab83b --- /dev/null +++ b/documentation/themes/themes-overview.asciidoc @@ -0,0 +1,77 @@ +--- +title: Overview +order: 1 +layout: page +--- + +[[themes.overview]] += Overview + +Vaadin separates the appearance of the user interface from its logic using +__themes__. Themes can include Sass or CSS style sheets, custom HTML layouts, +and any necessary graphics. Theme resources can also be accessed from +application code as [classname]#ThemeResource# objects. + +Custom themes are placed under the [filename]#VAADIN/themes/# folder of the web +application (under [filename]#WebContent# in Eclipse or +[filename]#src/main/webapp# in Maven projects). This location is fixed -- the +[filename]#VAADIN# folder contains static resources that are served by the +Vaadin servlet. The servlet augments the files stored in the folder by resources +found from corresponding [filename]#VAADIN# folders contained in JARs in the +class path. For example, the built-in themes are stored in the +[filename]#vaadin-themes.jar#. + +<> illustrates the contents of a theme. + +[[figure.themes.theme-contents]] +.Contents of a Theme +image::img/theme-contents-hi.png[] + +The name of a theme folder defines the name of the theme. The name is used in +the [literal]#++@Theme++# annotation that sets the theme. A theme must contain +either a [filename]#styles.scss# for Sass themes, or [filename]#styles.css# +stylesheet for plain CSS themes, but other contents have free naming. We +recommend that you have the actual theme content in a SCSS file named after the +theme, such as [filename]#mytheme.scss#, to make the names more unique. + +We also suggest a convention for naming the folders as [filename]#img# for +images, [filename]#layouts# for custom layouts, and [filename]#css# for +additional stylesheets. + +Custom themes need to extend a base theme, as described in +<>. Copying and modifying an existing theme is also possible, but +it is not recommended, as it may need more work to maintain if the modifications +are small. + +You use a theme by specifying it with the [literal]#++@Theme++# annotation for +the UI class of the application as follows: + + +[source, java] +---- +@Theme("mytheme") +public class MyUI extends UI { + @Override + protected void init(VaadinRequest request) { + ... + } +} +---- + +A theme can contain alternate styles for user interface components, which can be +changed as needed. + +In addition to style sheets, a theme can contain HTML templates for custom +layouts used with [classname]#CustomLayout#. See +<> for details. + +Resources provided in a theme can also be accessed using the +[classname]#ThemeResource# class, as described in +<>. This allows displaying theme resources in component icons, in the +[classname]#Image# component, and other such uses. + + + diff --git a/documentation/themes/themes-responsive.asciidoc b/documentation/themes/themes-responsive.asciidoc new file mode 100644 index 0000000000..b4377f9b66 --- /dev/null +++ b/documentation/themes/themes-responsive.asciidoc @@ -0,0 +1,286 @@ +--- +title: Responsive Themes +order: 10 +layout: page +--- + +[[themes.responsive]] += Responsive Themes + +((("[classname]#responsive# extension", id="term.themes.responsive", range="startofrange"))) + + +((("CSS selections"))) +((("extension"))) +Vaadin includes support for responsive design which enables size range +conditions in CSS selectors, allowing conditional CSS rules that respond to size +changes in the browser window on the client-side. + +ifdef::web[] +See the link:https://vaadin.com/blog/-/blogs/3126636[Vaadin Blog article on +Responsive design] for some additional +information. +endif::web[] + +You can use the [classname]#Responsive# extension to extend either a component, +typically a layout, or the entire UI. You specify the component by the static +[methodname]#makeResponsive()# method. + + +---- +// Have some component with an appropriate style name +Label c = new Label("Here be text"); +c.addStyleName("myresponsive"); +content.addComponent(c); + +// Enable Responsive CSS selectors for the component +Responsive.makeResponsive(c); +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.responsive.basic[on-line example, window="_blank"]. + +You can now use [literal]#++width-range++# and [literal]#++height-range++# +conditions in CSS selectors as follows: + + +---- +/* Basic settings for all sizes */ +.myresponsive { + padding: 5px; + line-height: 36pt; +} + +/* Small size */ +.myresponsive[width-range~="0-300px"] { + background: orange; + font-size: 16pt; +} + +/* Medium size */ +.myresponsive[width-range~="301px-600px"] { + background: azure; + font-size: 24pt; +} + +/* Anything bigger */ +.myresponsive[width-range~="601px-"] { + background: palegreen; + font-size: 36pt; +} +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.responsive.basic[on-line example, window="_blank"]. + +You can have overlapping size ranges, in which case all the selectors matching +the current size are enabled. + +ifdef::web[] +Note that responsive themes currently +link:https://dev.vaadin.com/ticket/16249[do not work together with] stylesheets +or widget sets loaded from a different domain than the Vaadin application. Such +resources must be loaded from the same domain as the application. The problem +occurs only in Firefox. A SecurityError is shown in the debug window. The +limitation concerns stylesheets such as for web fonts served from external +sites, as described in +<>. +endif::web[] + +ifdef::web[] +[[themes.responsive.wrap]] +== Flexible Wrapping + +You can use the [classname]#CssLayout# to have automatic wrap-around when the +components in the layout would go off right side of the layout. Components that +wrap must, however, have either undefined or fixed width, and thereby can not +utilize the full area of the screen. With the [classname]#Responsive# extension, +you can have more flexible wrap-around that gives the component tiles maximum +width. + +In the following, we have a text and image box, which are laid out horizontally +with 50-50 sizing if the screen is wide enough, but wrap to a vertical layout if +the screen is narrow. + + +---- +CssLayout layout = new CssLayout(); +layout.setWidth("100%"); +layout.addStyleName("flexwrap"); +content.addComponent(layout); + +// Enable Responsive CSS selectors for the layout +Responsive.makeResponsive(layout); + +Label title = new Label("Space is big, really big"); +title.addStyleName("title"); +layout.addComponent(title); + +Label description = new Label("This is a " + + "long description of the image shown " + + "on the right or below, depending on the " + + "screen width. The text here could continue long."); +description.addStyleName("itembox"); +description.setSizeUndefined(); +layout.addComponent(description); + +Image image = new Image(null, + new ThemeResource("img/planets/Earth.jpg")); +image.addStyleName("itembox"); +layout.addComponent(image); +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.responsive.flexwrap[on-line example, window="_blank"]. + +The SCSS could be as follows: + + +---- +/* Various general settings */ +.flexwrap { + background: black; + color: white; + + .title { + font-weight: bold; + font-size: 20px; + line-height: 30px; + padding: 5px; + } + + .itembox { + white-space: normal; + vertical-align: top; + } + + .itembox.v-label {padding: 5px} +} + +.flexwrap[width-range~="0-499px"] { + .itembox {width: 100%} +} + +.flexwrap[width-range~="500px-"] { + .itembox {width: 50%} +} +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.responsive.flexwrap[on-line example, window="_blank"]. + +The layout in the wide mode is shown in <>. + +[[figure.theme.responsive.flexwrap]] +.Flexible Wrapping +image::img/addon-responsive-flexwrap.png[] + +You could also play with the [literal]#++display: block++# vs +[literal]#++display: inline-block++# properties. + +Notice that, while the [classname]#Responsive# extension makes it possible to do +various CSS trickery with component sizes, the normal rules for component and +layout sizes apply, as described in +<> and elsewhere, and you should always check the size behaviour of the +components. In the above example, we set the label to have undefined width, +which disables word wrap, so we had to re-enable it. + +endif::web[] + +ifdef::web[] +[[themes.responsive.display]] +== Toggling the Display Property + +((("display (CSS +property)"))) +The [literal]#++display++# property allows especially powerful ways to offer +radically different UIs for different screen sizes by enabling and disabling UI +elements as needed. For example, you could disable some parts of the UI when the +space gets too small, but bring forth navigation buttons that, when clicked, add +component styles to switch to the hidden parts. + +In the following, we simply show alternative components based on screen width: + + +---- +CssLayout layout = new CssLayout(); +layout.setWidth("100%"); +layout.addStyleName("toggledisplay"); +content.addComponent(layout); + +// Enable Responsive CSS selectors for the layout +Responsive.makeResponsive(layout); + +Label enoughspace = + new Label("This space is big, mindbogglingly big"); +enoughspace.addStyleName("enoughspace"); +layout.addComponent(enoughspace); + +Label notenoughspace = new Label("Quite small space"); +notenoughspace.addStyleName("notenoughspace"); +layout.addComponent(notenoughspace); +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.responsive.display[on-line example, window="_blank"]. + +The SCSS could be as follows: + + +---- +/* Common settings */ +.toggledisplay { + .enoughspace, .notenoughspace { + color: white; + padding: 5px; + } + + .notenoughspace { /* Really small */ + background: red; + font-weight: normal; + font-size: 10px; + line-height: 15px; + } + + .enoughspace { /* Really big */ + background: darkgreen; + font-weight: bold; + font-size: 20px; + line-height: 30px; + } +} + +/* Quite little space */ +.toggledisplay[width-range~="0-499px"] { + .enoughspace {display: none} +} + +/* Plenty of space */ +.toggledisplay[width-range~="500px-"] { + .notenoughspace {display: none} +} +---- +See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.responsive.display[on-line example, window="_blank"]. + +endif::web[] + +ifdef::web[] +[[themes.responsive.demos]] +== Responsive Demos + +You can find a simple responsive demo at +link:http://demo.vaadin.com/responsive/[demo.vaadin.com/responsive]. It +demonstrates the flexible wrapping technique described in +<>. + +The +link:http://demo.vaadin.com/book-examples-vaadin7/book/#themes.responsive.basic[Book +Examples] demo provides the examples given in this chapter, as well as some +others. + +((("Parking +demo"))) +((("TouchKit", "Parking +demo"))) +The Parking demo for TouchKit, mentioned in +<>, uses a responsive theme to adapt to mobile +devices with different screen sizes and when the screen orientation changes. + +endif::web[] + +(((range="endofrange", startref="term.themes.responsive"))) + + diff --git a/documentation/themes/themes-sass.asciidoc b/documentation/themes/themes-sass.asciidoc new file mode 100644 index 0000000000..4b1f529de1 --- /dev/null +++ b/documentation/themes/themes-sass.asciidoc @@ -0,0 +1,156 @@ +--- +title: Syntactically Awesome Stylesheets (Sass) +order: 3 +layout: page +--- + +[[themes.sass]] += Syntactically Awesome Stylesheets (Sass) + +Vaadin uses Sass for stylesheets. Sass is an extension of CSS3 that adds nested +rules, variables, mixins, selector inheritance, and other features to CSS. Sass +supports two formats for stylesheet: Vaadin themes are written in SCSS ( +[filename]#.scss#), which is a superset of CSS3, but Sass also allows a more +concise indented format ( [filename]#.sass#). + +Sass can be used in two basic ways in Vaadin applications, either by compiling +SCSS files to CSS or by doing the compilation on the fly. The latter way is +possible if the development mode is enabled for the Vaadin servlet, as described +in +<>. + +[[themes.sass.overview]] +== Sass Overview + +[[themes.sass.overview.variables]] +=== Variables + +Sass allows defining variables that can be used in the rules. + + +[source, css] +---- +$textcolor: blue; + +.v-button-caption { + color: $textcolor; +} +---- + +The above rule would be compiled to CSS as: + + +[source, css] +---- +.v-button-caption { + color: blue; +} +---- + +Also mixins can have variables as parameters, as explained later. + + +[[themes.sass.overview.nesting]] +=== Nesting + +Sass supports nested rules, which are compiled into inside-selectors. For +example: + + +[source, css] +---- +.v-app { + background: yellow; + + .mybutton { + font-style: italic; + + .v-button-caption { + color: blue; + } + } +} +---- + +is compiled as: + + +[source, css] +---- +.v-app { + background: yellow; +} + +.v-app .mybutton { + font-style: italic; +} + +.v-app .mybutton .v-button-caption { + color: blue; +} +---- + + +[[themes.sass.overview.mixins]] +=== Mixins + +Mixins are rules that can be included in other rules. You define a mixin rule by +prefixing it with the [literal]#++@mixin++# keyword and the name of the mixin. +You can then use [literal]#++@include++# to apply it to another rule. You can +also pass parameters to it, which are handled as local variables in the mixin. + +For example: + + +[source, css] +---- +@mixin mymixin { + background: yellow; +} + +@mixin othermixin($param) { + margin: $param; +} + +.v-button-caption { + @include mymixin; + @include othermixin(10px); +} +---- + +The above SCSS would translated to the following CSS: + + +[source, css] +---- +.v-button-caption { + background: yellow; + margin: 10px; +} +---- + +You can also have nested rules in a mixin, which makes them especially powerful. +Mixing in rules is used when extending Vaadin themes, as described in +<>. + +Vaadin themes are defined as mixins to allow for certain uses, such as different +themes for different portlets in a portal. + + + +[[themes.sass.basic]] +== Sass Basics with Vaadin + +We are not going to give in-depth documentation of Sass and refer you to its +excellent documentation at http://sass-lang.com/. In the following, we give just +basic introduction to using it with Vaadin. + +You can create a new Sass-based theme with the Eclipse plugin, as described in +<>. + + + + diff --git a/documentation/themes/themes-valo.asciidoc b/documentation/themes/themes-valo.asciidoc new file mode 100644 index 0000000000..5ae5a1b37b --- /dev/null +++ b/documentation/themes/themes-valo.asciidoc @@ -0,0 +1,440 @@ +--- +title: Valo Theme +order: 7 +layout: page +--- + +[[themes.valo]] += Valo Theme + +Valo is the word for light in Finnish. The Valo theme incorporates the use of +light in its logic, in how it handles shades and highlights. It creates lines, +borders, highlights, and shadows adaptively according to a background color, +always with contrasts pleasant to human visual perception. Auxiliary colors are +computed using an algorithmic color theory to blend gently with the background. +The static art is complemented with responsive animations. + +The true power of Valo lies in its configurability with parameters, functions, +and Sass mixins. You can use the built-in definitions in your own themes or +override the defaults. Detailed documentation of the available mixins, +functions, and variables can be found in the Valo API documentation available at +http://vaadin.com/valo. + +[[themes.valo.use]] +== Basic Use + +Valo is used just like other themes. Its optional parameters must be given +before the [literal]#++@import++# statement. + +Your project theme file, such as [filename]#mytheme.scss#, included from the +[filename]#styles.scss# file, could be as follows: + + +---- +// Modify the base color of the theme +$v-background-color: hsl(200, 50%, 50%); + +// Import valo after setting the parameters +@import "../valo/valo"; + +.mythemename { + @include valo; + + // Your theme's rules go here +} +---- + +If you need to override mixins or function definitions in the valo theme, you +must do that after the import statement, but before including the valo mixin. +Also, with some configuration parameters, you can use variables defined in the +theme. In this case, they need to be overridden after the import statement. + + +[[themes.valo.variables]] +== Common Settings + +In the following, we describe the optional parameters that control the visual +appearance of the Valo theme. In addition to the ones given here, component +styles have their own parameters, listed in the sections describing the +components in the other chapters. + +[[themes.valo.variables.general]] +=== General Settings + +$v-background-color(default:[literal]#++hsl(210, 0%, 98%)++#):: The background color is the main control parameter for the Valo theme and it is +used for computing all other colors in the theme. If the color is dark (has low +luminance), light foreground colors that give high contrast with the background +are automatically used. + ++ +You can specify the color in any way allowed in CSS: hexadecimal RGB color code, +RGB/A value specified with [methodname]#rgb()# or [methodname]#rgba()#, HSL/A +value specified with [methodname]#hsl()# or [methodname]#hsla()#. You can also +use color names, but it should be avoided, as not all CSS color names are +currently supported. + +$v-app-background-color(default:$v-background-color):: Background color of the UI's root element. You can specify the color in any way +allowed in CSS. + +$v-app-loading-text(default:[literal]#++""++#):: A static text that is shown under the loading spinned while the client-side +engine is being loaded and started. The text must be given in quotes. The text +can not be localized currently. + + ++ +---- +$v-app-loading-text: "Loading Resources..."; +---- +$v-line-height(default:[literal]#++1.55++#):: Base line height for all widgets. It must be given a unitless number. + + ++ +---- +$v-line-height: 1.6; +---- + + + +[[themes.valo.variables.fonts]] +=== Font Settings + +$v-font-size(default:[literal]#++16px++#):: Base font size. It should be specified in pixels. + + ++ +---- +$v-font-size: 18px; +---- +$v-font-weight(default:[literal]#++300++#):: Font weight for normal fonts. The size should be given as a numeric value, not +symbolic. + + ++ +---- +$v-font-weight: 400; +---- +$v-font-color(default: computed):: Foreground text color, specified as any CSS color value. The default is computed +from the background color so that it gives a high contrast with the background. + +$v-font-family(default:[literal]#++"Open Sans", sans-serif++#):: Font family and fallback fonts as a comma-separated list. Font names containing +spaces must be quoted. The default font Open Sans is a web font included in the +Valo theme. Other used Valo fonts must be specified in the list to enable them. +See <>. + + ++ +---- +$v-font-family: "Source Sans Pro", sans-serif; +---- +$v-caption-font-size(default:[literal]#++round($v-font-size * 0.9)++#):: Font size for component captions. The value should be a pixel value. + +$v-caption-font-weight(default:[literal]#++max(400, $v-font-weight)++#):: Font weight for captions. It should be defined with a numeric value instead of +symbolic. + + + + +[[themes.valo.variables.layout]] +=== Layout Settings + + +++++ +$v-unit-size (default: round(2.3 * $v-font-size)) + This is the base size for various layout measures. It is + directly used in some measures, such as button height and + layout margins, while other measures are derived from + it. The value must be specified in pixels, with a suitable + range of 18-50. + $v-unit-size: 40px;$v-layout-margin-top$v-layout-margin-right$v-layout-margin-bottom$v-layout-margin-left (default: $v-unit-size) + Layout margin sizes for all built-in layout components, + when the margin is enabled with + setMargin(), as described in + . + $v-layout-spacing-vertical and + $v-layout-spacing-horizontal (default: + round($v-unit-size/3)) + Amount of vertical or horizontal space when spacing is enabled + for a layout with setSpacing(), as + described in . + +++++ + + +[[themes.valo.variables.component]] +=== Component Features + +The following settings apply to various graphical features of some components. + +$v-border(default:[literal]#++1px solid (v-shade 0.7)++#):: Border specification for the components that have a border. The thickness +measure must be specified in pixels. For the border color, you can specify any +CSS color or one of the [literal]#++v-tint++#, [literal]#++v-shade++#, and +[literal]#++v-tone++# keywords described later in this section. + +$v-border-radius(default:[literal]#++4px++#):: Corner radius for components that have a border. The measure must be specified +in pixels. + + ++ +---- +$v-border-radius: 8px; +---- +$v-gradient(default:[literal]#++v-linear 8%++#):: Color gradient style for components that have a gradient. The gradient style may +use the following keywords: [literal]#++v-linear++# and +[literal]#++v-linear-reverse++#. The opacity must be given as percentage between +0% and 100%. + + ++ +---- +$v-gradient: v-linear 20%; +---- +$v-bevel(default:[literal]#++inset 0 1px 0 v-tint, inset 0 -1px 0 v-shade++#):: Inset shadow style to define how some components are "raised" from the +background. The value follows the syntax of CSS box-shadow, and should be a list +of insets. For the bevel color, you can specify any CSS color or one of the +[literal]#++v-tint++#, [literal]#++v-shade++#, and [literal]#++v-tone++# +keywords described later in this section. + ++ +//TODO Check the meaning of v-tone +$v-bevel-depth(default:[literal]#++30%++#):: Specifies the "depth" of the bevel shadow, as applied to one of the color +keywords for the bevel style. The actual amount of tint, shade, or tone is +computed from the depth. + +$v-shadow(default:[literal]#++0 2px 3px v-shade++#):: Default shadow style for all components. As with $v-bevel, the value follows the +syntax of CSS box-shadow, but without the [literal]#++inset++#. For the shadow +color, you can specify any CSS color or one of the [literal]#++v-tint++# or +[literal]#++v-shade++# keywords described later in this section. + +$v-shadow-opacity(default:[literal]#++5%++#):: Specifies the opacity of the shadow, as applied to one of the color keywords for +the shadow style. The actual amount of tint or shade is computed from the depth. + +$v-focus-style(default:[literal]#++0 0 0 2px rgba($v-focus-color, .5)++#):: Box-shadow specification for the field focus indicator. The space-separated +values are the horizontal shadow position in pixels, vertical shadow position in +pixels, blur distance in pixels, spread distance in pixels, and the color. The +color can be any CSS color. You can only specify the color, in which case +defaults for the position are used. [methodname]#rgba()# or [methodname]#hsla()# +can be used to enable transparency. + ++ +For example, the following creates a 2 pixels wide orange outline around the +field: + + ++ +---- +$v-focus-style: 0 0 0 2px orange; +---- +$v-focus-color(default:[literal]#++valo-focus-color()++#):: Color for the field focus indicator. The [methodname]#valo-focus-color()# +function computes a high-contrast color from the context, which is usually the +background color. The color can be any CSS color. + +$v-animations-enabled(default:[literal]#++true++#):: Specifies whether various CSS animations are used. + +$v-hover-styles-enabled(default:[literal]#++true++#):: Specifies whether various [literal]#++:hover++# styles are used for indicating +that mouse pointer hovers over an element. + +$v-disabled-opacity(default:[literal]#++0.5++#):: Opacity of disabled components, as described in +<>. + +$v-selection-color(default:[literal]#++$v-focus-color++#):: Color for indicating selection in selection components. + +$v-default-field-width(default:[literal]#++$v-unit-size * 5++#):: Default width of certain field components, unless overridden with +[methodname]#setWidth()#. + +$v-error-indicator-color(default:[literal]#++#ed473b++#):: Color of the component error indicator, as described in +<>. + +$v-required-field-indicator-color(default:[literal]#++$v-error-indicator-color++#):: Color of the required indicator in field components, as described in +<>. + + + +Color specifications for $v-border, $v-bevel, and $v-shadow may use, in addition +to CSS colors, the following keywords: + +v-tint:: Lighter than the background color. + +v-shade:: Darker than the background color. + +v-tone:: Adaptive color specification: darker on light background and lighter on dark +background. Not usable in $v-shadow. + + + +For example: + + +---- +$v-border: 1px solid v-shade; +---- + +You can fine-tune the contrast by giving a weight parameter in parentheses: + + +---- +$v-border: 1px solid (v-tint 2); +---- + + +---- +$v-border: 1px solid (v-tone 0.5); +---- + + +[[themes.valo.variables.optimization]] +=== Theme Compilation and Optimization + +$v-relative-paths(default:[literal]#++true++#):: This flags specifies whether relative URL paths are relative to the currently +parsed SCSS file or to the compilation root file, so that paths are correct for +different resources. Vaadin theme compiler parses URL paths differently from the +regular Sass compiler (Vaadin modifies relative URL paths). Use +[literal]#++false++# for Ruby compiler and [literal]#++true++# for Vaadin Sass +compiler. + +$v-included-components(default: component list):: Theme optimization parameter to specify the included component themes, as +described in <>. + +$v-included-additional-styles(default:[literal]#++$v-included-components++#):: Theme optimization parameter that lists the components for which the additional +component stylenames should be included. See <> for more +details. + + + + + +[[themes.valo.mixins]] +== Valo Mixins and Functions + +Valo uses Sass mixins and functions heavily to compute various theme features, +such as colors and shades. Also, all component styles are mixins. You can use +the built-in mixins or override them. For detailed documentation of the mixins +and functions, please refer to the Valo API documentation available at +http://vaadin.com/valo/api. + + +[[themes.valo.fonts]] +== Valo Fonts + +Valo includes the following custom fonts: + +* Open Sans +* Source Sans Pro +* Roboto +* Lato +* Lora + +The used fonts must be specified with the $v-font-family parameter for Valo, in +a fallback order. A font family is used in decreasing order of preference, in +case a font with higher preference is not available in the browser. You can +specify any font families and generic families that browsers may support. In +addition to the primary font family, you can use also others in your +application. To enable using the fonts included in Valo, you need to list them +in the variable. + + +---- +$v-font-family: 'Open Sans', sans-serif, 'Source Sans Pro'; +---- + +Above, we specify Open Sans as the preferred primary font, with any sans-serif +font that the browser supports as a fallback. In addition, we include the Source +Sans Pro as an auxiliary font that we can use in custom rules as follows: + + +---- +.v-label pre { + font-family: 'Source Sans Pro', monospace; +} +---- + +This would specify using the font in any [classname]#Label# component with the +[literal]#++PREFORMATTED++# content mode. + + +[[themes.valo.component]] +== Component Styles + +Many components have component-specific styles to make them smaller, bigger, and +so forth. You can specify the component styles with [methodname]#addStyleName()# +using the constants defined in the [classname]#ValoTheme# enum. + + +---- +table.addStyleName(ValoTheme.TABLE_COMPACT); +---- + +For a complete up-to-date list of component-specific styles, please refer to +Vaadin API documentation on the [classname]#ValoTheme# enum. Some are also +described in the component-specific styling sections. + +[[themes.valo.component.disabling]] +=== Disabling Component Styles + +Component styles are optional, but all are enabled by default. They can be +enabled on per-component basis with the $v-included-additional-styles parameter. +It defaults to $v-included-components and can be customized in the same way, as +described in <>. + + +[[themes.valo.component.parameters]] +=== Configuration Parameters + +The following variables control some common component styles: + +$v-scaling-factor--tiny(default:[literal]#++0.75++#):: A scaling multiplier for [literal]#++TINY++# component styles. + +$v-scaling-factor--small(default:[literal]#++0.85++#):: A scaling multiplier for [literal]#++SMALL++# component styles. + +$v-scaling-factor--large(default:[literal]#++1.2++#):: A scaling multiplier for [literal]#++LARGE++# component styles. + +$v-scaling-factor--huge(default:[literal]#++1.6++#):: A scaling multiplier for [literal]#++HUGE++# component styles. + + + + + +[[themes.valo.optimization]] +== Theme Optimization + +Valo theme allows optimizing the size of the compiled theme CSS by including the +rules for only the components actually used in the application. The included +component styles can be specified in the [literal]#++$v-included-components++# +variable, which by default includes all components. The variable should include +a comma-separated list of component names in lower-case letters. Likewise, you +can specify which additional component styles, as described in +<>, should be included using the +$v-included-additional-styles parameter and the same format. The list of +additional styles defaults to $v-included-components. + +For example, if your UI contains just [classname]#VerticalLayout#, +[classname]#TextField#, and [classname]#Button# components, you could define the +variable as follows: + + +---- +$v-included-components: + verticallayout, + textfield, + button; +---- + +You can use the [methodname]#remove()# function reversely to remove just some +component themes from the standard selection. + +For example, with the following you can remove the theme definitions for the +[classname]#Calendar# component: + + +---- +$v-included-components: remove($v-included-components, calendar); +---- + +Note that in this case, you need to give the statement __after__ the +[literal]#++@import++# statement for the Valo theme, because it overrides a +variable by using its value that is defined in the theme. + + + + -- cgit v1.2.3