Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
App themes
You can create custom themes for apps. Set a theme
property in your app descriptor.
Node name | Value |
---|---|
modules | |
flower-shop | |
apps | |
plants | |
appClass | info.magnolia.ui.framework.app.BaseApp |
icon | icon-plants |
label | Plants |
theme | orange |
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.
Changing the Vaadin theme for the entire application is technically more advanced than app themes. Unless you already have a good understanding of Sass, as well as themes in the Vaadin world, you should probably read about it through the Vaadin documentation first.
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>