Developing CSS for AdminCentral, with on-the-fly Sass compilation

Tired of restarting Magnolia just to see your single-line CSS change in resurface? Me too.

How do I know it works?

1. You should see the Sass compiler output in the console, with fat red (harmless) WARNINGS.

oct. 05, 2018 11:10:21 AM com.vaadin.sass.internal.ScssStylesheet warning
WARNING: Base-level rule contains the parent-selector-referencing character '&'; the character will be removed:
BlockNode [&.v-app, &.v-app-loading {
		Mixin node [name: valo-app-style args: Actual argument list [ArgumentList []]]
	}]
oct. 05, 2018 11:10:21 AM com.vaadin.sass.internal.ScssStylesheet warning
WARNING: Base-level rule contains the parent-selector-referencing character '&'; the character will be removed:
BlockNode [.v-ff & .v-tree-node-drag-top:before, .v-ff & .v-tree-node-drag-bottom:after {
		Rule node [line-height: 1px;]
	}]
oct. 05, 2018 11:10:22 AM com.vaadin.server.VaadinServlet persistCacheEntry

2. After the first compilation, refreshing the page should also recompile and produce the same output over and over again, every time the CSS is reloaded.

Disable Sass compilation in Maven (optional)

The main point is first to make sure there's no precompiled styles.css under /VAADIN/themes/resurface-admincentral (resp. admincentral for M5), in src and/or target directories.

In order to prevent pre-compiled files ending up on the classpath and being picked up, disable theme Sass compilation in pom files.

Disabling the top-level theme compilation should be enough for the standard case; but your mileage may vary.

For the new 6.0 theme: In magnolia-admincentral/pom.xml, comment out the build tag (or just the Sass compilation part inside).

For the old 5.x theme: Repeat above for magnolia-ui-admincentral/pom.xml.

If it still doesn't work, you might as well try disabling theme compilation in magnolia-resurface-theme and magnolia-ui-vaadin-theme, respectively.

Disable Vaadin productionMode

In WEB-INF/web.xml, set productionMode to false, i.e. change the relevant part to:

<context-param>
  <description>Vaadin production mode</description>
  <param-name>productionMode</param-name>
  <param-value>false</param-value>
</context-param>

Should result in the following upon server startup (actually Vaadin servlet startup/reload)

=================================================================
Vaadin is running in DEBUG MODE.
Add productionMode=true to web.xml to disable debug features.
To show debug window, add ?debug to your application URL.
=================================================================

Apart from Sass on-the-fly compilation, this enables:

use of the debug window (through ?debug GET param)
use of the ?restartApplication flag
- though the M6 UI shouldn't need it anymore for the time being, since it currently does not @PreserveUIOnRefresh

—Alternatively, replace the filter class of the VaadinStatic servlet with info.magnolia.admincentral.VaadinServletDispatchingFilter, to infer that from magnolia.properties (see below).

If magnolia.develop is true in magnolia.properties, productionMode will be set to false, and resourceCacheTime will be set to 0.

If any of these parameters is configured under /server/filters/servlets/<servlet-name>/parameters, these configured parameters will be used.

Enable Magnolia dev mode

In magnolia.properties (most likely WEB-INF/config/default/magnolia.properties), set magnolia.develop to true.

Use cache-less Vaadin servlet

The default Vaadin servlet caches compiled SCSS files, based on a last-modification timestamp, and re-compiles whenever that timestamp changes. Unfortunately, timestamps are only correctly resolved for the file system, so files from jars (like in our case) will always have the same default timestamp and thus forever be cached.

We have a class extending VaadinServlet circumventing that cache (thanks Mika :bow:): In the config tree, set /server/filters/servlets/VaadinStatic@servletClass (localhost link) to info.magnolia.ui.dev.NoScssCacheVaadinServlet.

Include Vaadin Sass compiler

Depending on your setup, you might need to explicitly set a maven dependency to `vaadin-sass-compiler` scoped to runtime in your webapp:

<dependency>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-sass-compiler</artifactId>
  <scope>runtime</scope>
</dependency>

Use a CSS Reload browser add-on (optional)

Install a CSS Reload add-on, like CSS Reloader for Firefox, and bind it to keyboard shortcut, such as F9. This speeds things up as well, by only reloading the CSS, but not the page/whole Vaadin application.

It still doesn't work?

Don't forget about the browser cache. To be on the safe side, keep the CSS file open in a separate tab and hit Ctrl+F5 after changes (hard reload without cache). This works for Linux and Windows, I'm sure OS X has some shortcut too.

It still doesn't work!

Dust off the debugger, fix it, and extend this page. :shrug:

Page tree