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
|
---
title: Compiling Sass Themes
order: 4
layout: page
---
[[themes.compiling]]
= Compiling Sass Themes
Sass themes must be compiled to CSS understood by browsers. Compilation can be
done with the Vaadin Sass Compiler, which you can run in Eclipse, Maven, or it
can be run on-the-fly when the application is loaded in the browser. You can
also use any other Sass compiler.
[[themes.compiling.on-the-fly]]
== Compiling On the Fly
The easiest way to develop Sass themes is to compile them at runtime, when the page is loaded.
The Vaadin servlet does this automatically if a compiled theme CSS file is not found from the theme folder.
You need to have the SCSS source files placed in the theme folder.
The theme is compiled when the [filename]#styles.css# is first requested from the server.
If you edit the Sass theme, it is recompiled the next time you reload the page.
The on-the-fly compilation takes a bit time, so it is only available when the
Vaadin servlet is in the development mode, as described in
<<../application/application-environment#application.environment.parameters,"Other
Servlet Configuration Parameters">>. Also, it requires the theme compiler and
all its dependencies to be in the class path of the servlet. At least for
production, you must compile the theme to CSS, as described next.
NOTE: If the on-the-fly compilation does not seem to work, ensure that your build script has not generated a pre-compiled CSS file.
If a [filename]#styles.css# file is found by the servlet, the compilation is skipped.
Disable theme compilation in your local development environment and delete the existing
[filename]#styles.css# file to enable on-the-fly compilation. Note that
theme compilation should not be disabled for production builds.
[[themes.compiling.eclipse]]
== Compiling in Eclipse
If using Eclipse and the Vaadin Plugin for Eclipse, its project wizard creates a
Sass theme. It includes [menuchoice]#Compile Theme# command in the toolbar to
compile the project theme to CSS. Another command compiles also the widget set.
[[figure.themes.compiling.eclipse]]
.Compiling Sass Theme
image::img/eclipse-theme-compiler.png[]
The [filename]#WebContent/VAADIN/mytheme/styles.scss# and any Sass sources
included by it are compiled to [filename]#styles.css#.
[[themes.compiling.maven]]
== Compiling with Maven
To compile the themes with Maven, you need to include the built-in themes as a
dependency:
[source, xml]
----
...
<dependencies>
...
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-themes</artifactId>
<version>${vaadin.version}</version>
</dependency>
</dependencies>
...
----
This is automatically included at least in the
[literal]#++vaadin-archetype-application++# archetype for Vaadin applications.
The actual theme compilation is most conveniently done by the Vaadin Maven
Plugin with [literal]#++update-theme++# and [literal]#++compile-theme++# goals.
[source, xml]
----
...
<plugin>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-maven-plugin</artifactId>
...
<executions>
<execution>
...
<goals>
<goal>clean</goal>
<goal>resources</goal>
<goal>update-theme</goal>
<goal>update-widgetset</goal>
<goal>compile-theme</goal>
<goal>compile</goal>
</goals>
</execution>
</executions>
----
Once these are in place, the theme is compiled as part of relevant lifecycle
phases, such as [literal]#++package++#.
[subs="normal"]
----
[command]#mvn# [parameter]#package#
----
You can also compile just the theme with the [package]#compile-theme# goal:
[subs="normal"]
----
[command]#mvn# [parameter]#vaadin:compile-theme#
----
ifdef::web[]
[[themes.compiling.command-line]]
== Compiling in Command-line
You can compile Sass style sheets to CSS either with the Vaadin Sass compiler or
the standard one. The [filename]#styles.css# of a custom theme should be the
compilation target. When compiled before deployment, the source files do not
need to be in the theme folder.
You can run the Vaadin Sass compiler in a theme folder as follows:
[subs="normal"]
----
[command]#java# [parameter]#-cp# [replaceable]#'../../../WEB-INF/lib/*'# com.vaadin.sass.SassCompiler styles.scss styles.css
----
The [parameter]#-cp# parameter should point to the class path where the Vaadin
Sass Compiler and theme JARs are located. In the above example, they are assumed
to be located in the [filename]#WEB-INF/lib# folder of the web application. If
you have loaded the Vaadin libraries using Ivy, as is the case with projects
created with the Vaadin Plugin for Eclipse, the Vaadin libraries are stored in
Ivy's local repository. Its folder hierarchy is somewhat scattered, so we
recommend that you retrieve the libraries to a single folder. We recommend using
an Ant script as is described next.
endif::web[]
[[themes.compiling.ant]]
== Compiling with Ant
With Apache Ant, you can easily resolve the dependencies with Ivy and compile
the theme with the Theme Compiler included in Vaadin as follows. This build step
can be conveniently included in a WAR build script.
Start with the following configuration:
[source, xml]
----
<project xmlns:ivy="antlib:org.apache.ivy.ant"
name="My Project" basedir="../"
default="package-war">
<target name="configure">
<!-- Where project source files are located -->
<property name="src-location" value="src" />
... other project build definitions ...
<!-- Name of the theme -->
<property name="theme" value="mytheme"/>
<!-- Compilation result directory -->
<property name="result" value="build/result"/>
</target>
<!-- Initialize build -->
<target name="init" depends="configure">
<!-- Construct and check classpath -->
<path id="compile.classpath">
<!-- Source code to be compiled -->
<pathelement path="${src-location}" />
<!-- Vaadin libraries and dependencies -->
<fileset dir="${result}/lib">
<include name="*.jar"/>
</fileset>
</path>
<mkdir dir="${result}"/>
</target>
----
You should first resolve all Vaadin libraries to a single directory, which you
can use for deployment, but also for theme compilation.
----
<target name="resolve" depends="init">
<ivy:retrieve
pattern="${result}/lib/[module]-[type]-[artifact]-[revision].[ext]"/>
</target>
----
Then, you can compile the theme as follows:
----
<!-- Compile theme -->
<target name="compile-theme"
depends="init, resolve">
<delete dir="${result}/VAADIN/themes/${theme}"/>
<mkdir dir="${result}/VAADIN/themes/${theme}"/>
<java classname="com.vaadin.sass.SassCompiler"
fork="true">
<classpath>
<path refid="compile.classpath"/>
</classpath>
<arg value="WebContent/VAADIN/themes/${theme}/styles.scss"/>
<arg value="${result}/VAADIN/themes/${theme}/styles.css"/>
</java>
<!-- Copy theme resources -->
<copy todir="${result}/VAADIN/themes/${theme}">
<fileset dir="WebContent/VAADIN/themes/${theme}">
<exclude name="**/*.scss"/>
</fileset>
</copy>
</target>
</project>
----
|
