1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
|
---
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
<<../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
<<../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.
ifdef::vaadin7[]
Field components are described in <<../components/components-fields#components.fields.field,"Field Interface">>.
endif::vaadin7[]
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.
|