LESS Module

Last modified by Thomas Mortagne on 2017/03/28 15:08

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

XWiki Development Team

Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise

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 replaced it afterwards since it does not have good performances.

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 some functions to compile a skin file, compute a color theme from a LESS file, and to clear the cache.

Performances

Cache

Every LESS files 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 couple color theme/filesystem skin.

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

Until 8.0M2, the cache was cleaned at the wiki start-up (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 performances 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 could use the LESS CSS script service like this:

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

It could be useful when you do some changes on the LESS files of your skin, in the filesystem, 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 performances!

Simultaneous compilations (Since 7.4.2 and 8.0M2)

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

To change this setting, you could 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, some 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
Tags:
Created by Guillaume Delhumeau on 2014/05/19 11:38
    

Get Connected