LESS Module
 | Add the ability to use the LESS preprocessor in XWiki |
| Type | JAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | Since 6.1 |
Table of contents
Description
This modules offer a Java integration of LESS CSS, using Less4j.
It is also able to compile, at runtime, LESS files located into the current skin directory, in the WAR.
Presentation
You can read 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.
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:
<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:
$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.
Simultaneous compilations
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
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:
#-# Generate sourcemaps inline in the CSS files.
#-#
#-# The default is:
# lesscss.generateInlineSourceMaps = false
