Color Theme Feature for Flamingo

Last modified by Vincent Massol on 2024/02/26 17:52



Related Proposals

Color Themes

Currently, we have the ability to create different color themes for Colibri.

Capture du 2014-04-15 10:47:05.png

But the pre-visualisation of the theme is clearly based on Colibri and it does not reflect the results on Flamingo.


  1. We can modify the existing Color Theme Application to display an other previsualisation if Flamingo is used.
  2. We can create a new Color Theme Application dedicated to Flamingo, as the current one is dedicated to Colibri.


Flamingo is based on Bootstrap, which defines a lot of customizable variables, more than we have for colibri (such as font size, font family, etc...). A lot of applications already exists
on the web to help users to fill these variables to create their own themes:

Maybe we could integrate one of them in XWiki, or taking inspiration from them.

Question: should we propose to set all these variables in our Color Theme Application or only some of them?



Since we are using LESS to build Flamingo, and since there is an Client-Side LESS compiler, we can use it to refresh all the XWiki UI instead of the previsualisaton area. In any way, we need to propose a kind a previsuliasation because refreshing the current UI will not show all the use-cases.

Skin Implementation

Currently, we use LESS to generate the CSS file during the build via a maven plugin, not during the runtime.

Implementation using velocity variables (LESS compiler called BEFORE velocity engine)

It is possible to use Velocity variables in the LESS files:

@body-bg: $theme.pageBackgroundColor;
// when @body-bg is used in a CSS class, LESS will just replace it by the string "$theme.pageBackgroundColor"

Then, the velocity variables will be interpreted at the runtime, as usual.

But this approach is limited, it makes impossible to use some bootstrap mixins like darken() (used to generate a darken color from a parameter) because LESS cannot compute a value from the string "$theme.pageBackgroundColor". It means that we have to change such calls in the bootstrap sources.

Pros :

  • quite easy to implement

Cons :

  • needs to modify the bootstrap sources (not good for upgrades)

Implementation using LESS at the runtime (LESS compiler called AFTER velocity engine)

The idea is to call the velocity engine BEFORE the LESS compiler, so any reference to a velocity variables is replaced by the proper value and the bootstrap mixins work without any problem.

Pros :

  • more powerful, we can use the bootstrap mixins
  • we do not modify the bootstrap sources, we just provide our variables.less file
  • a good step into the direction of proposing LESS features to our users

Cons :

  • need to use LESS at the runtime
    • what about performances? we should probably cache the result
    • how to implement the @import feature?
    • we need to add both flamingo & bootstrap sources in our instances
  • much harder to implement. Overkill?

I have started to work on a prototype and I have good results.

Alternative: rewrite some bootstrap mixins with velocity macros

We can, for example, write our own version of darken(), executed by velocity at the runtime.

Pros :

  • no need to have the LESS compiler at the runtime

Cons :

  • we still have to modify the bootstrap sources to use our velocity macros instead of their mixins, but it could probably be done automatically
  • we have to maintain our own version of the bootstrap mixins as velocity macros


The UI to create/edit a Color Theme should be split in two sections:

  1. a WYSIWYG section, with some bootstrap variables and a color picker, that refreshes in real-time the CSS of the page
  2. a textarea where users can directly write some LESS code

1) is for the regular users.
2) is for people who wants to integrate a bootstrap kit found on the web



The "WYSIWIG" editor could be something like this Bootstrap fancyboot or a modified version of the current one.


2 options

  1. we do not offer more variables that the current editor does, we just change the way it is displayed in the editor (for the rest, there is the textarea field). Then we could use the existing ColorThemes.ColorThemeClass.
  2. we offer a completely different set of variables and we need an other, incompatible with colibri, ColorTheme class.


A lot of customs CSS uses the color theme variables

These variables (such as $theme.textSecondaryColor) does not always have an equivalent in Bootstrap. However, it is easy to add some code in colorThemeInit.vm to do a mapping between the variables of the new color theme and the variables of the old one. But if some variables have been set in the text-area, we need to parse the LESS code to know what is the final value of a bootstrap variable.

Idea: Parse the generated CSS to get the computed variables, with some CSS classes specific to that purpose.

Should a color theme be specific to a skin?

In this case, we need a mechanism to express if a color theme is compatible with a skin.


Get Connected