diff options
Diffstat (limited to 'documentation/themes/themes-creating.asciidoc')
| -rw-r--r-- | documentation/themes/themes-creating.asciidoc | 283 |
1 files changed, 0 insertions, 283 deletions
diff --git a/documentation/themes/themes-creating.asciidoc b/documentation/themes/themes-creating.asciidoc deleted file mode 100644 index dcd2c5034a..0000000000 --- a/documentation/themes/themes-creating.asciidoc +++ /dev/null @@ -1,283 +0,0 @@ ---- -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 -<<dummy/../../../framework/themes/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 -<<dummy/../../../framework/themes/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 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>>. - -[[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. - - - - |