Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 283 insertions, 0 deletions

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
+<<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/&lt;theme&gt;/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.
+
+
+
+