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.

The AdminCentral back end reflects the Magnolia brand. Our brand identity is important to us. Here are the things you can and cannot change.

What you are allowed to change

• App group colors. Help users identify apps that are specific to your business.
• App icons. Create your own icon font. Use an icon that communicates the intended use of your app clearly.
• App theme. Create a your own Vaadin theme if it’s important that users can identify your own apps also when the app is open.
• App layout. Create a custom app layout if you need to do something really different such as display graphs or charts.
• AdminCentral background color. Want to make it blue? Go ahead, make editors feel at home. Just keep the elements listed below intact.

What you are NOT allowed to change

• Magnolia logo. The logo should stay in place and visible at all times in AdminCentral.
• App Launcher, Pulse and Favorites icons
• Icons that ship with the MagnoliaIcons font.
• DIN font used in user interface text.
• App launcher, Pulse and Favorites layouts. We designed the space and positioning of these fundamental layout elements to work well in various devices. We don’t support changing the layout or adding new elements.

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>