LESS Module and LESS CSS

The LESS Module allows to compile LESS files located in the current skin folder at run-time and provides a Java integration of LESS CSS using the LESS CSS Compiler for Java.

As seen in the API available on GitHub, the LESS module has 4 main components:

In order to run LESS CSS on the Java Virtual Machine we use Rhino, a JavaScript interpreter which unfortunately offers a very low performance.

Usage

You can expose the LESS module API in Velocity using a script service:$services.lesscss

For the Flamingo skin, the LESS files located in the folder "/skins/flamingo/less" are compiled ans the result is a String. 

Example: $services.lesscss.compileSkinFile("style.less.vm").

Velocity is interpreted before the LESS compiler. This means that we can use @import "someFile.less"; for any other file located in the same directory but Velocity won't be interpreted on those files.

Also, for the moment it is not possible to write LESS code directly into "XWiki.StyleSheetExtension" objects.

Cache Mechanism

The code compiled by LESS is cached on the filesystem to avoid unnecessary computation. In a multi-wiki environment there is one cache per wiki.

The cached is flushed when a color theme or a skin is created, updated or deleted. It is possible to manually flush the cache using script services as follows: $services.lesscss.clearCache() OR $services.lesscss.clearCache("wikiId").

By default, the cache is cleaned at start-up but you can keep the cache of the previous run-time by adding the following settings in the "xwiki/WEB-INF/cache/infinispan/config.xml" file:

<!-- LESS CSS cache -->
<namedCache name="lesscss.skinfiles.cache">
<loaders>
  <loader class="org.infinispan.loaders.file.FileCacheStore" purgeOnStartup="false">
    <!-- Let XWiki cache module set the proper location -->
  </loader>
</loaders>
</namedCache>

LESS CSS

Variables

LESS variables control commonly used values in a single location. They are just like "constants" and can only be defined once.

Example

@main-color: green;

.myClass1 {
  color: @main-color;
}

.myClass2 {
  background-color: @main-color;
}

Extend

Extend is a LESS pseudo-class for merging the selector it is put on with the selectors that match what it references. Thus, the generated code is optimized.

Example

.myClass1 {
  border: 1px solid red;
  box-shadow: 1px 1px 12px #555;
}

.myClass2 {
  &: extend(.myClass1);
  background: blue;
}

will output

.myClass1, .myClass2 {
  border: 1px solid red;
  box-shadow: 1px 1px 12px #555;
}

.myClass2 {
  background: blue;
}

The extend is either attached to a selector or placed into a rule-set and it actually looks like a pseudo-class with a selector parameter that is optionally followed by the keyword all.

Example

.c:extend(.d all) {
  // extends all instances of ".d" e.g. ".x.d" or ".d.x"
}
.c:extend(.d) {
  // extends only the instances where the selector will be output as just ".d"
}

You can extend several classes at once using: .e:extend(.f, .g) {}.

Mix-ins

Mix-ins are the solution when wanting to include the properties from one rule-set to another rule-set. For instance, the LESS code

.myCustomBorder(@color) {
  border: 1px solid @color;
  box-shadow: 1px 1px 12px #555;
}

.myClass1 {
  .myCustomBorder(blue);
}

.myClass2 {
  .myCustomBorder(red);
}

will produce the output:

.myClass1 {
  border: 1px solid blue;
  box-shadow: 1px 1px 12px #555;
}

.myClass2 {
  border: 1px solid red;
  box-shadow: 1px 1px 12px #555;
}

Includes

To import styles from other style sheets you can use the @import directive as follows: 

  • @import "layout.less"; - the file "layout.less" will be directly included in the output
  • @import (reference)"lib.less"; - the "lib.less" will be imported but the file will not be outputted; this is equivalent to {{velocity output="false" /}}.

LESS offers several additional extensions that can be used with @import for more flexibility:

  • @import (reference) - used to include a file without outputting it.
  • @import (inline) - used to include external files without processing them.
  • @import (less) - used to treat imported files as LESS files regardless of their extension.
  • @import (css) - used to treat imported files as CSS files regardless of their extension.
  • @import (once) - this is the default behavior of @import statements. It means the file is imported only once and subsequent import statements for that file will be ignored.
  • @import (multiple) - used for importing a file multiple times.

Built-in Functions

LESS provides a collection of built-in functions:

    

Search this space