Theming is an essential topic to address when developing a complex application UI as in Magnolia 5. It ensures a consistent look & feel across the whole application, as well as it can help structuring where such styling rules are defined in the project. We took the opportunity to tackle this for alpha3: starting small with basic Vaadin fields, and introducing a sustainable setup for separating theme styles from the Admincentral specific application styles. We also opened up the door to UI extensibility, with the possibility to inject a custom theme for an app.

This concept belongs to the following story Unable to locate Jira server for this macro. It may be due to Application Link configuration.

 

Project structure

Most notably, the magnolia theme was introduced, along with its sampler Vaadin application. We created a project setup that helps separating styles coming from different levels, with the following advantages:

  • Styles can be decoupled per role
  • Style definitions and implementation are in same module
  • We could remove duplication of theme styles across various locations
  • This ensures visual design consistency in UI elements throughout Magnolia 5
  • We will eventually end up with even more themes as the ui project is properly modularized (actionbar, fields, dialogs, workbench, etc.).

See the full details in the table below:

5.0-alpha25.0-alpha3Roles
  • magnolia-ui-admincentral
    • @Theme("admincentraltheme")
      AdmincentralUI  
  • magnolia-ui-admincentral
    • @Theme("admincentral") AdmincentralUI  
    • themes/admincentral
      • includes magnolia, admincentraltheme
  • the theme used by AdmincentralUI
  • includes the magnolia theme
  • should contain application specific style rules
  • mostly style names from the admincentral module.
-
  • magnolia-ui-vaadin-theme
    • themes/magnolia
      • includes base
  • proper branding theme to give basic Vaadin components the Magnolia visual style
  • extends Vaadin's base theme, rather than chameleon theme; we don't need its visual features
  • only style names from vaadin, e.g. '.v-button', '.v-textfield'.
-
  • magnolia-ui-vaadin-theme-sampler
    • @Theme("themesampler") ThemeSamplerUI
    • themes/themesampler
      • includes magnolia
  • not part of the final admincentral theme
  • simply includes magnolia theme into a basic sample Vaadin application
  • for theme development
  • magnolia-ui-vaadin-widgetset
    • themes/admincentraltheme
      • includes chameleon
  • magnolia-ui-vaadin-widgetset
    • themes/admincentraltheme
  • legacy theme in the widgetset module, currently still holds most styles for the Admincentral
  • meant to contain only base style rules for magnolia widgets, i.e. without magnolia branding
  • only style names from our widget java classes, e.g. '.v-actionbar'.
  • bound to be renamed to e.g. magnolia-widgets

 

Sass - Syntactically Awesome Stylesheets

We brought the power of Sass into our stylesheets. Sass is an extension of CSS for which there is built-in support in Vaadin 7 (SassCompiler). It essentially provides the following features:

Variables
  • $green: #689600; /* Magnolia 5 Green */
Nesting
  • .v-filterselect { ...
     .    v-filterselect-button {
           background-color: $c06;
Mixins
  • @mixin magnolia {
          @include base; 

Sass files in Vaadin can be compiled on the fly, which is handy during development, or at build time.
The ultimate advantage is also that the generated stylesheet is served as one 'big' CSS file, helping dramatically reduce the number of download requests that we had with plain CSS @import rules.

 

Magnolia Theme Sampler

The theme sampler can be run as a standalone Vaadin webapp, but it is not built into magnolia_ui.
It's mostly helpful for developing the magnolia branding theme for Vaadin components, and represents them the way they look inside Magnolia 5.
It may well grow over time, and may also be used to ensure visual design consistency across browsers.


Next steps

Original concept page was updated for a 2nd iteration, see Concept - UI theming and extensibility, level 2.