From a1b265c318dbda4a213cec930785b81e4c0f7d2b Mon Sep 17 00:00:00 2001 From: elmot Date: Fri, 25 Sep 2015 16:40:44 +0300 Subject: Framework documentation IN Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581 --- documentation/themes/themes-valo.asciidoc | 440 ++++++++++++++++++++++++++++++ 1 file changed, 440 insertions(+) create mode 100644 documentation/themes/themes-valo.asciidoc (limited to 'documentation/themes/themes-valo.asciidoc') 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