Hi all,
I am currently developing an add-on that includes a Sass mixin that takes care of certain aspects of how the visuals appear.
However, I found it very hard to find out the right steps for packaging the add-on such that the Vaadin applications using that add-on will actually pick up the add-on stylesheet. I could not do it without studying source code and even then, it took me quite a bit of trial and error to get it to work. I would like to share my insights with whoever is attempting to do the same.
My add-on is called “synergy”. Its purpose is to provide a very flexible navigation system for Vaadin applications. The add-on is setup up as a Vaadin Maven project with a regular theming structure, so the synergy mixin is defined in src/main/webapp/VAADIN/themes/synergy/synergy.scss. To make this mixin available to the application project, you must to two things:
#1 Include the directory VAADIN in the add-on jar at root level, so it looks like this:
META-INF/
VAADIN/
de/
To achieve this, you simply have to declare the webapp directory as a resource in the POM:
<resources>
<resource>
<directory>src/main/webapp</directory>
</resource>
</resources>
(probably obvious to others, but I learned something new here)
#2 Add a Vaadin-Stylesheets entry to META-INF/MANIFEST.MF. You can let the maven-jar-plugin take care of it like this:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>2.6</version>
<configuration>
<archive>
<index>true</index>
<manifest>
<addClasspath>true</addClasspath>
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
</manifest>
<manifestEntries>
<Vaadin-Package-Version>1</Vaadin-Package-Version>
<Vaadin-License-Title>${Vaadin-License-Title}</Vaadin-License-Title>
<Vaadin-Stylesheets>VAADIN/themes/synergy/synergy.scss</Vaadin-Stylesheets>
</manifestEntries>
</archive>
</configuration>
</plugin>
I only found out about this requirement by reading the source code of
https://vaadin.com/api/7.4.5/com/vaadin/server/widgetsetutils/ClassPathExplorer.html
. Afterwards I found this ticket
https://dev.vaadin.com/ticket/11390
, but it seems the information has not made it into the book.
After I did that, I finally was seeing these long-awaited log lines when I built the application, telling me that it was actually picking up the add-on’s stylesheet:
[INFO]
--- vaadin-maven-plugin:7.4.2:update-theme (default) @ try14springboot ---
[INFO]
Updating theme VAADIN\themes\try14
[INFO]
Widgetsets found from classpath:
[INFO]
Addon styles found from classpath:
[INFO]
VAADIN/themes/synergy/synergy.scss in jar:file:D:/Users/sre/.m2/repository/de/syngenio/vaadin/synergy/0.0.1-SNAPSHOT/synergy-0.0.1-SNAPSHOT.jar!/
Note that the stylesheet referred to in the add-on manifest (here synergy.scss) must be named exactly like the mixin (here synergy), otherwise it will break the addons.scss generated by Vaadin’s theme compiler:
/* This file is automatically managed and will be overwritten from time to time. */
/* Do not manually edit this file. */
/* Provided by synergy-0.0.1-SNAPSHOT.jar */
@import "../../../VAADIN/themes/synergy/synergy.scss";
/* Import and include this mixin into your project theme to include the addon themes */
@mixin addons {
@include synergy;
}
Well, I hope this was helpful to someone.
Best regards and happy adding-on!
Stefan