App theme

App themes

You can create custom themes for apps. Set a theme property in your app descriptor.

First, Magnolia will look for a Vaadin theme stylesheet at /VAADIN/themes/orange/styles.css, following the same pattern as any Vaadin theme (typically under src/main/resources).

• You can also use Sass. Vaadin will try to serve the compiled css on the fly, if the Vaadin productionMode is off. For production, you will have to configure Sass compilation in your Maven pom. See Compiling your Sass themes below.
• Magnolia will then inject this stylesheet into the document's head when the app starts, using Vaadin's CSSInject addon.

It will also add a CSS class name to the app's container div element, such as app-orange. With this, you can make your CSS selectors more specific, and make sure your styles apply only within your app.

Please also mind that, because they are configured through the app descriptor, app themes enable you to use multiple themes for different Magnolia apps, at the same time (unlike the advanced technique described below).

Customizing the admincentral theme

In some cases, you may want to customize styles outside of any app, e.g. in the apps launcher, or in the Pulse message views. There, app themes are not sufficient, but you may still configure the Vaadin theme used by the entire admincentral.

Vaadin themes

Like for any Vaadin application, there can be only one Vaadin theme per Vaadin UI. In Magnolia's case, this is the AdmincentralUI.

Sass themes offer the advantage of being composed from several other Vaadin themes, through Sass mixins. Themes are ultimately compiled and served as one big chunk of CSS.

Implementing the custom theme

In order to implement your own theme, you have to use Sass. First, you must always "inherit" from Magnolia's default admincentral theme, i.e. by importing and including its Sass mixin.
Only then, you may add your custom styles, or include additional Vaadin themes you wish to use.

For more information, please read about Vaadin themes  and Sass  in the Vaadin framework documentation. See also the Sass website.

Configuring the custom theme

Once your Sass theme is ready, and it includes both the admincentral mixin and your custom styles, tell Magnolia to use it.

Edit your webapp's magnolia.properties file and set the key magnolia.ui.vaadin.theme.
The expected value is a theme name as Vaadin expects it, i.e. the name of the theme folder under src/main/resources/VAADIN/themes.

Compiling your Sass themes

Development-time settings

When you develop custom Sass themes (.scss), set Vaadin's productionMode to false in your web.xml, so that Vaadin compiles your stylesheet on the fly:

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

If you write a plain CSS theme, you don't need to do this.

Production-time settings

When you go to production, you don't want to keep Vaadin's productionMode to false. Therefore, the Sass theme is not compiled on the fly anymore.

You need to compile your Sass theme in your module build.

This may be achieved with the groovy maven plugin, as shown below (given the Sass compiler is on the classpath). Alternatively, you may use also the Vaadin maven plugin, as mentioned in Compiling Sass Themes, in the Vaadin documentation.

<plugins>
  <plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>groovy-maven-plugin</artifactId>
    <executions>
      <execution>
        <phase>process-resources</phase>
        <goals>
          <goal>execute</goal>
        </goals>
        <configuration>
          <source>
            import com.vaadin.sass.SassCompiler
            SassCompiler.main(["${project.basedir}/src/main/resources/VAADIN/themes/orange/styles.scss", "${project.basedir}/target/classes/VAADIN/themes/orange/styles.css"] as String[])
          </source>
        </configuration>
      </execution>
    </executions>
  </plugin>
</plugins>