LESS Module

Version 27.1 by Guillaume Delhumeau on 2016/02/18 17:36

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

XWiki Development Team

Rating
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.

Tags:
    

Get Connected