Page History
Abstract
Themeing Theming and Styling need to be improved, especially the stylesheets are quite a mess 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. We expect this concept to lead to proper themeing theming and styling guidelines, as well as reorganizing and cleaning up the stylesheets.
...
Info | ||
---|---|---|
| ||
App styles extensibility was reviewed by API team, Project structure: magnolia-ui-vaadin-theme remains in magnolia_ui, as well as the magnolia-ui-vaadin-theme-sampler, which is excluded from the magnolia_ui build. Installing modules which come with custom widgets needs to recompile the whole widgetset, this is a major blocker right now. |
1.
...
Theming
Problem
- We don't have true themeing theming 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 stylesheets
- Some style rules are simply duplicated across several stylesheets (forms vs. dialogs)
- All vaadin standard UI components should look visually integrated into magnolia
- Styling could be applied in a more light-weight way
Proposal
- 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
- Then we try to give proper Magnolia themeing theming to other standard vaadin widgets, e.g. error messages, loading indicators
- Maybe we can cleanup our widgets a bit
Decision
- We use SASS
- We cannot specify multiple themes in the
@Theme
annotation- But we can add
@include
SASS rules to use themes as mixins
- But we can add
- 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
- We ultimately serve on the fly compiled scss only for development
- For production we compile SASS statically during the build. Static compilation is done inside the Maven profile 'sass-compile-production'.
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 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 add the magnolia-ui-theme project (location to be specified)
- 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
- 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
3. Extensibility
Problem
- An app developers cannot define styles for her own app in its own module
- It is not clearly specified how an app developer would add a custom widget to her app
- There is no guideline either on how an app developer would add her own icons for her app and actions
Proposal
- We cannot use
@Theme
annotation for third party apps because theme is set on AdmincentralUI, apps are not vaadin UIs - We use CSSInject to dynamically load an
@import
rule which references a CSS stylesheet- optionally we try to reference a SASS one
Decision
- Create custom annotation @AppTheme to assign theme for an App.
...
- Theming is implemented at the AppInstanceController class that checks during an App startup whether the App class is annotated with the AppTheme annotation.
- App container DIV will be added "app-%THEMENAME%" CSS class so style selectors can reference App.
- App developer is expected to add the theme as a standard vaadin theme to be found in /VAADIN/themes/%THEMENAME%/styles.css
Suggestion box
- The magnolia theme application could ultimately switch between expected screenshot and actual fields, to help on browser support
- Structure:
- magnolia-ui-admincentral
@Theme("admincentral") AdmincentralUI
- themes/admincentral includes magnolia
- magnolia-ui-vaadin-theme
- themes/magnolia includes base, commonbase, shellbase
- magnolia-ui-vaadin-theme-sampler
@Theme("themesampler") ThemeSamplerUI
- themes/themesampler includes magnolia
- magnolia-ui-vaadin-widgets-common
- themes/commonbase
- magnolia-ui-vaadin-widgets-editor
- themes/pageeditor
- magnolia-ui-vaadin-widgets-shell
- themes/shellbase
- themes/shellbase
- magnolia-ui-admincentral
- Use CSSInject add-on to support third-party app styles https://vaadin.com/directory#addon/cssinject
- Inserts styles into <head><style>...</
- Can load external stylesheets in this manner: new CSSInject(getUI()).setStyles("@import url('http://theme files/styles.css');");
- Set this at App level, eventually processing it in BaseApp
- Enable SASS for STK themes
...