LESS Module

Last modified by Vincent Massol on 2024/07/05 14:35

cssAdd the ability to use the LESS preprocessor in XWiki
TypeJAR
Category
Developed by

XWiki Development Team

Rating
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

Since 6.1

Description

This modules offer a Java integration of LESS CSS, using Less4j.

Before the version 7.0RC1, XWiki used the LESS CSS Compiler for Java. We have since replaced it due to it having terrible performance.

It is also able to compile, at runtime, LESS files located into the current skin directory, in the WAR.

Presentation

You can read this presentation that we have made to introduce LESS and how to use in XWiki.

Components

This module provides 4 main components:

  • LESSCompiler: allows you to compile some LESS code, with some options. The CSS generated is minified.
  • LESSSkinFileCompiler: allows you to compile some LESS file located in the directory of any skin in the web-application. Velocity is executed before the LESS compiler is used, and every @imports will be checked on the /less directory inside the current skin. The results is cached and shared to every users, so you should not put velocity code which is context-dependent.
  • LESSSkinFileCache: caches the results compiled with the previous component. You can clear it when it is needed.
  • LESSColorThemeConverter: compute a color theme compatible with the Color Theme Application from a LESS file.

Script Services

This modules offer a script services called $services.lesscss.
It provides functions to compile a skin file, compute a color theme from a LESS file, and to clear the cache.

Performances

Cache

Every LESS file compiled in XWiki is cached. The cache is cleaned each time a color theme is created, updated, or deleted in a wiki. There is one cache per color theme/filesystem skin couple.

Before XWiki 6.2.3 and XWiki 6.3M2, there was only one cache per wiki. This means that if a color theme was saved on wiki A, the cache was not cleared on wiki B, even if the color theme was used in wiki B. See XWIKI-10776.

Until 8.0M2, the cache was cleaned at the wiki startup (so that if the format of what is cached changes over XWiki releases, the cache can be rebuilt). If you want to keep the cache of the previous runtime (for performance reasons), you could add the following settings in xwiki/WEB-INF/cache/infinispan/config.xml:

<!-- LESS CSS cache -->
<local-cache name="lesscss.skinfiles.cache">
 <persistence>
   <file-store purge="false">
     <!-- Let XWiki cache module set the proper location -->
   </file-store>
 </persistence>
</local-cache>

Cleaning

To manually clean the cache, you can use the LESS CSS script service like this:

{{velocity}}
  $services.lesscss.clearCache()
{{/velocity}}

This is useful when making changes to the LESS files of your skin in the filesystem (rather than through a template override), because XWiki does not handle cache cleaning when a change is made outside the wiki.

Don't put this code in a frequently hit page, or you will get terrible performance!

Simultaneous compilations (Since 7.4.2 and 8.0M2)

Since a LESS compilation is quite costly, there is a limit for the number of compilations that can be done simultaneously. Depending on your server's resources, you should put a little or a big number.

To change this setting, edit xwiki.properties:

#-------------------------------------------------------------------------------------
# LESS CSS
#-------------------------------------------------------------------------------------

#-# [Since 7.4.2, 8.0M2]
#-# The number of LESS compilations that can be performed simultaneously. Put a little number if your resources are
#-# limited.
#-#
#-# The default is:
# lesscss.maximumSimultaneousCompilations = 4

If the number is too high, a lot of LESS compilations can happen in the same time, eating a lot of memory, and causing an OutOfMemory exception.

Debugging LESS files with CSS Source Maps (Since 8.0RC1)

When you debug a LESS-compiled file, you get a unique CSS file, even if the sources were split in multiple files. It makes the debugging of CSS rules more complicated. For this reason, you can enable the "source maps." Even if you have a unique CSS file at the end, special comments have been added to it and the browser interprets them to let you know which file was the source.

To enable them, you need to edit xwiki.properties:

#-# [Since 8.0RC1]
#-# Generate sourcemaps inline in the CSS files.
#-#
#-# The default is:
# lesscss.generateInlineSourceMaps = false

Get Connected