Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 440 insertions, 0 deletions

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 <<themes.valo.fonts>>.
+
+
++
+----
+$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
+
+
+++++
+<variablelist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xl="http://www.w3.org/1999/xlink"><varlistentry><term><varname>$v-unit-size</varname> (default: <literal>round(2.3 * $v-font-size)</literal>)</term><listitem><para>
+                                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.
+                            </para><programlisting>$v-unit-size: 40px;</programlisting></listitem></varlistentry><varlistentry><term><varname>$v-layout-margin-top</varname></term><term><varname>$v-layout-margin-right</varname></term><term><varname>$v-layout-margin-bottom</varname></term><term><varname>$v-layout-margin-left</varname> (default: <literal>$v-unit-size</literal>)</term><listitem><para>
+                                Layout margin sizes for all built-in layout components,
+                                when the margin is enabled with
+                                <methodname>setMargin()</methodname>, as described in
+                                <xref linkend="layout.settings.margins"/>.
+                            </para></listitem></varlistentry><varlistentry><term><varname>$v-layout-spacing-vertical</varname> and
+                            <varname>$v-layout-spacing-horizontal</varname> (default:
+                            <literal>round($v-unit-size/3)</literal>)</term><listitem><para>
+                                Amount of vertical or horizontal space when spacing is enabled
+                                for a layout with <methodname>setSpacing()</methodname>, as
+                                described in <xref linkend="layout.settings.spacing"/>.
+                            </para></listitem></varlistentry></variablelist>
+++++
+
+
+[[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
+<<dummy/../../../framework/components/components-features#components.features.enabled,"Enabled">>.
+
+$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
+<<dummy/../../../framework/application/application-errors#application.errors.error-indicator,"Error
+Indicator and Message">>.
+
+$v-required-field-indicator-color(default:[literal]#++$v-error-indicator-color++#):: Color of the required indicator in field components, as described in
+<<dummy/../../../framework/components/components-fields#components.fields.field,"Field
+Interface">>.
+
+
+
+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 <<themes.valo.optimization>>.
+
+$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 <<themes.valo.component>> 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.optimization>>.
+
+
+[[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
+<<themes.valo.component>>, 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.
+
+
+
+