Integrate a Bootstrap theme in XWiki? An example with Bootswatch

Last modified by Guillaume Delhumeau on 2023/03/09 11:37

Jan 06 2015

With the arrival of Flamingo in XWiki, we now have a nice, modern and responsive skin. Moreover, it has been built using Bootstrap, the great CSS framework which is very popular nowadays.

One of the Bootstrap's characteristics is the fact that we can find a lot of themes on the Web. 

The good news is that we are able to integrate them in XWiki, through the Flamingo Theme Application. In this post, I am going to show you how to proceed, with a theme provided by Bootswatch.WarningThis article has been written using an XWiki 6.4 snapshot, and the instructions I give cannot work with a version prior to 6.2.4.

For this article, I have chosen the Journal theme, that you can see right under:

preview-bootswatch.png

The principle of the Bootswatch theme is to override the Bootstrap variables and to provide some LESS code that you can use in your own LESS file. 

Information

If you are wondering what LESS is, I would answer that it is a great language on top of CSS to write more easily some good styles, with the possibility to use functions and to write re-usable classes. Bootstrap has been written with this, enjoying the power of this preprocessor. My description is very succinct and if you want to know more, please visit the website of the project.

Since the Bootwatch team is kind, we can download their LESS files. There are 2 of them: variables.less and bootswatch.less.

Now we are going to create a new Flamingo Theme. To do that, we go to the Flamingo Theme Application (Administration > Presentation > Manage color theme) and we create a new theme called "BootswatchJournal".
create-a-new-theme.png

We reach the theme editor:
new-theme.png

In this editor, we can find a lot of Bootstrap variables that we can easily override. We just need to fill the fields. The variables are sorted by categories, such as "Base colors", "Typography", etc... On the right, a live preview will show us any change we do. Great.

But we are not going to fill all existing fields with the Bootswatch content. It would be too much work and the theme editor does not expose all the existing variables but only the most used ones.
Fortunately, the theme editor enable us to directly write some LESS code to inject in the skin. Magical!

So we go to the "Advanced" section, to fill the "@lessCode" textarea.
lessCode.png

As you can see, a warning message tells us that the live preview is not able to handle the LESS code we will enter. That is the limitation of the tool... Not too bad, we can live with this.

Now, we will just take the content of the previously downloaded variables.less and bootswatch.less files. We paste it, one under the other. First variables.less, then bootstwach.less. We save the page, go back to the Flamingo Theme Application, and use our new theme on the wiki.

Enjoy the result:
first-results.png

Damn. It looks quite nice but icons of the top menus are broken. So let's go back to the editor, and modify the LESS code.

This line makes a problem:
@icon-font-path:          "../fonts/";

The problem is that XWiki does not store the fonts in the "fonts" directory. Actually, XWiki already redefines this variable internally, so what we have to do is only to comment this line:

// XWiki already redefines this variables
//@icon-font-path:          "../fonts/";

We also add a comment to explicitly show the change we have made on the Bootswatch theme. This is good for the maintainability, if we want to upgrade to a newer version of Bootswatch in the future.

Now we save that, and we look at the results (don't forget to clear your browser's cache):
good-results.png

Nice, we have made it! Now, we can still add some custom LESS code, in the theme editor, to add some shiny improvements, and to fix stuff there and there. But in less than 5 minutes, we have got a very nice result!

I have applied this method for each Bootswatch theme and you can enjoy them in XWiki, since it is bundled by default in XWiki Enterprise! For some of them, I needed to add some custom code, but nothing difficult. It took me half a day to do a basic integration of all the 16 themes in XWiki!

I hope you enjoy it and that you will integrate some nice themes in XWiki too.

Guillaume ...