|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274 |
- ---
- 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
- <<themes-overview#figure.themes.theme-contents,"Contents of a Theme">>. 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
- <<themes-compiling#themes.compiling,"Compiling Sass Themes">>.
-
- 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 style names 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 add 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
-
- 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>>.
-
- [[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
- <<dummy/../../../framework/themes/themes-fonticon#themes.fonticon,"Font
- Icons">>.
-
- 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
- <<dummy/../../../framework/portal/portal-liferay#portal.liferay.install,"Installing
- Vaadin Resources">>.
-
- 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
- <<dummy/../../../framework/gwt/gwt-styling#gwt.styling,"Styling a Widget">>.
-
-
- [[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.
|