Page History

Abstract

Themeing Theming and Styling need still needs to be improved, especially the legacy stylesheets are still quite a mess messy as of 5.0-alpha2. Project structure needs to be reviewed to properly modularize styling and widgets, so that apps/views can be properly extended. alpha3. We expect this concept to lead to proper themeing and styling guidelinessecond iteration of the concept to give the magnolia theme a broader scope, as well as reorganizing and cleaning up to tackle the reorganization and clean-up of the stylesheets.

This concept also still belongs to the following user story.

...

Problem

1. Theming

Problem

• Stylesheets are still a mess (legacy admincentraltheme)
• We don't have true themeing so far, only fields in dialogs have decent styles
  
  • If I add a TextField and a Button in my app, they should also have the Magnolia style
• Stylesheets are a real mess
  
  • They're not properly modularized
  • Some rules don't belong to the right stylesheet
  • Widget styles and app styles are also mixed up inside these stylesheetsSome style rules are simply duplicated across several stylesheets (forms vs. dialogs)
• All vaadin standard UI components should look visually integrated into magnolia
• Styling could still be applied in a more light-weight way
• SASS needs to be compiled to CSS
  
  • On-fly compilation is intended for development use only
  • VaadinServlet processes SASS files and compiles them before HTTP request is returned
    
    • Problem: Our static resources path is not handled by the VaadinServlet and compilation does not take place.
  • Need script to compile .scss files into .css during production builds

Proposal

• We use SASS
• We cannot specify multiple themes in the @Theme annotation
  
  • But we can add @include SASS rules to use themes as mixins
• We have a MagnoliaThemeUI demo vaadin application that features UI components from vaadin, for theme development
  
  • either we put it in an external sandbox, with a dependency to magnolia-ui-theme
  • either we start getting theme outside magnolia_ui, because it has no dep here and can be built upstream
    
    • widgets can also make the move in a second step
• We start theme again, picking minimal rules from the existing CSS into new SASS stylesheets
  
  • We inherit the base theme
  • We start with standard vaadin fields
• Then we try to give proper Magnolia themeing to other standard vaadin widgets, e.g. error messages, loading indicators
  
  • Maybe we can cleanup our widgets a bit

• Any module should be able to add Sass compilation at build time

Proposal

• We complete theming for basic vaadin fields
  

  • Jira
    server Magnolia key MGNLUI-710

• We then tackle other subtasks in

  Jira
  server Magnolia key MGNLUI-704

• We could have Sass compilation in any vaadin-enabled UI module
  • For 3rd party modules, build-time Sass compilation could ultimately move to the bundle (same as widgetset)

Decision

-

2. Project structure and Widgetset

Problem

• It is hard to relate widget java classes - where style names are set - to their actual CSS rules
• All stylesheets even for widgets are in the theme directory, which is not necessarly bad but should be reviewed
  
  • We want these styles to remain dynamically loaded (not processed at GWT compilation time) so that it's easy to develop them
• We need to review the pattern for applying desktop vs. tablet styles as well
• Package structure of the common-widgets project could be clearer
• Naming of widget classes is inconsistent
  
  • Reevaluate usage of "v-" prefix in style names for magnolia widgets, this is not consistent right now
• As Sasha pointed out, there may also be room for Optimizing the WidgetSet
• There cannot be parallel widgetsets. They must be defined inside a tree structure and all widgetsets must be compiled only once into one compilation unit.
  
  • This leads to a problem if an App developer has to build the admincentral in order to have client side widgets.

...

• is always only one widgetset. It can aggregate as many other widgetsets (e.g. addons) but ultimately results into one compilation unit
  
  •  This is a critical issue because we need to recompile the whole widgetset after installing any module that comes with a custom widget (e.g. dam media editor)

Proposal

• We try to draw a meaningful separation for "shell-only" widgets
• Investigate a possibility to compile the widgetset during runtime. e.g during startup.
  
  • Need to investigate if it is possible to place compiled resources into a location that can be served

Decision

• We align on vaadin7 package structure (client/server/shared)
• We align naming of widget classes
  
  • we try to use *Widget / *Connector consistently
  • we drop client-side naming *View / *ViewImpl
  • we leave the v- prefix for standard vaadin component style names, we use m- prefix for magnolia widget styles
  • we don't use any prefix for application views
• We add the magnolia-ui-theme project
  
  • we start taking vaadin field styles from widgetset to here, using properly modularized SASS files
• We try to draw a meaningful separation for "shell-only" widgets
• Investigate a possibility to compile the widgetset during runtime. e.g during startup.
  
  • Need to investigate if it is possible to place compiled resources into a location that can be served

Decision

-

• take the widgetset project to the bundle

3. Extensibility

Problem

...

• It is not clearly specified clear how an app developer would add adds a custom widget to her app
• There is no guideline either on It is not clear how an app developer would add adds her own icons for her app and its actions

Proposal

• We cannot use @Theme annotation for third party apps because theme is set on admincentral
• We use CSSInject to dynamically load an @import rule which references a CSS stylesheet
  
  • optionally we try to reference a SASS one

-

Decision

-

Suggestion box

• The magnolia theme application could ultimately switch between expected screenshot and actual fields, to help on browser support
• Structure (base directory magnolia_ui):
  
  • magnolia-ui-vaadin-admincentral
    theme
    
    • themes/magnolia includes base, commonbase, shellbase
    • @Theme("admincentral")
      AdminCentralUI
    • themes
      admincentral
      include magnolia
  • magnolia-ui-vaadin-widgets-common
    
    • themes/commonbase
  • magnolia-ui-vaadin-widgets-editor
    
    • themes/pageeditor
    theme
    
    • @Theme("magnolia-theme-ui")
      MagnoliaThemeUI
    • themes
      
    • magnolia
      
      • include base
      • include magnolia-widgets-base
    magnolia-theme-ui
    include magnolia
  • magnolia-ui-widgetset
    themes
    magnoliavaadin-widgets-base
  Use CSSInject add-on to support multiple themes https://vaadin.com/directory#addon/cssinject
  • shell
    
    • themes/shellbase
  • Inserts styles into <body><head><style>..</
  • Can load external stylesheets in this manner:  new CSSInject(getUI()).setStyles("@import url('http://theme files/styles.css');");
• Enable SASS for STK themes

...