Category: less

Ever searched for a simple configuration, that lets you use your jetty-maven-plugin as you are used to, while working with LESS to simplify your stylesheets?

You cannot do both, use the Client-side mode of LESS to ease development and use the lesscss-maven-plugin to automatically compile the LESS-sources into CSS for production. That does not work, because your stylesheets must be linked in different ways if you are switching between the client-side mode – which is best for development – and the pre-compiled mode – which is best for production. For the client-side mode you need something like:

<link rel="stylesheet/less" type="text/css" href="styles.less" />
<script src="less.js" type="text/javascript"></script>

While, for the pre-compiled mode, you want to link to your stylesheets as usual, with:

<link rel="stylesheet" type="text/css" href="styles.css" />

While looking for a solution to this dilemma, I stumbled accross wro4j. Originally intended, to speed up page-delivery by combining and minimizing multiple resources into one through the use of a servlet-filter, this tool also comes with a maven-plugin, that let you do the same offline, while compiling your webapp.

The idea is, to use the wro4j-maven-plugin to compile and combine your LESS-sources into CSS for production and to use the wro4j filter, to dynamically deliver the compiled CSS while developing. This way, you do not have to alter your HTML-code, when switching between development and production, because you always link to the CSS-files.

So, lets get dirty!

Step 1: Configure wro4j

First, we configure wro4j, like as we want to use it to speed up our page. The details are explained and linked on wro4j’s Getting-Started-Page. In short, we just need two files: wro.xml and wro.properties.

wro.xml

wro.xml tells wro4j, which resources should be combined and how the result should be named. I am using the following configuration to generate all LESS-Sources beneath base/ into one CSS-file called base.css:

<groups xmlns="http://www.isdc.ro/wro">
  <group name="base">
    <css>/less/base/*.less</css>
  </group>

wro4j looks for /less/base/*.less inside the root of the web-context, which is equal to src/main/webapp in a normal maven-project. There are other ways to specifie the resources, which enable you to store them elswhere. But this approach works best for our goal, because the path is understandable for both: the wro4j servlet-filter, we are configuring now for our development-environment, and the wro4j-maven-plugin, that we will configure later for build-time compilation.

wro.properties

wro.properties in short tells wro4j, how or if it should convert the combined sources and how it should behave. I am using the following configuration to tell wro4j, that it should convert *.less-sources into CSS and do that on every request:

managerFactoryClassName=ro.isdc.wro.manager.factory.ConfigurableWroManagerFactory
preProcessors=cssUrlRewriting,lessCssImport
postProcessors=less4j
disableCache=true

First of all we specify the ConfigurableWroManagerFactory, because otherwise, wro4j would not pick up our pre- and post-processor-configuration. This is a little bit confusing, because wro4j is already reading the wro.properties-file – otherwise wro4j would never detect the managerFactoryClassName-directive – and you might think: “Why? He is already interpreting our configuration!” But belive me, he is not! You can read more about that in wro4j’s documentation. The disableCache=true is also crucial, because otherwise, we would not see the changes take effect when developing with jetty-maven-plugin later on. The pre-processors lessCssImport and cssUrlRewriting merge together all our LESS-resources under /less/base/*.less and do some URL-rewriting, in case you have specified paths to images, fonts or other resources inside your LESS-code, to reflect that the resulting CSS is found under /css/base.css and not /css/base/YOURFILE.css like the LESS-resources.

You can do much more with your resources here, for example minimizing. Also, there are countless configuration options to fine-tune the behaviour of wro4j. But for our goal, we are now only intrested in the compilation of our LESS-sources.

Step 2: Configure the wro4j servlet-filter

Configuring the filter in the web.xml is easy. It is explained in wro4j’s installation-insctuctions. But the trick is, that we do not want to configure that filter for the production-version of our webapp, because we want to compile the resources offline, when the webapp is build. To acchieve this, we can use the <overrideDescriptor>-Parameter of the jetty-maven-plugin.

<overrideDescriptor>

This parameter lets you specify additional configuration options for the web.xml of your webapp. I am using the following configuration for my jetty-maven-plugin:

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <configuration>
    <webApp>
      <overrideDescriptor>${project.basedir}/src/test/resources/jetty-web.xml</overrideDescriptor>
    </webApp>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>ro.isdc.wro4j</groupId>
      <artifactId>wro4j-core</artifactId>
      <version>${wro4j.version}</version>
    </dependency>
    <dependency>
      <groupId>ro.isdc.wro4j</groupId>
      <artifactId>wro4j-extensions</artifactId>
      <version>${wro4j.version}</version>
      <exclusions>
        <exclusion>
          <groupId>javax.servlet</groupId>
          <artifactId>servlet-api</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.apache.commons</groupId>
          <artifactId>commons-lang3</artifactId>
        </exclusion>
        <exclusion>
          <groupId>commons-io</groupId>
          <artifactId>commons-io</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.springframework</groupId>
          <artifactId>spring-web</artifactId>
        </exclusion>
        <exclusion>
          <groupId>com.google.code.gson</groupId>
          <artifactId>gson</artifactId>
        </exclusion>
        <exclusion>
          <groupId>com.google.javascript</groupId>
          <artifactId>closure-compiler</artifactId>
        </exclusion>
        <exclusion>
          <groupId>com.github.lltyk</groupId>
          <artifactId>dojo-shrinksafe</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.jruby</groupId>
          <artifactId>jruby-core</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.jruby</groupId>
          <artifactId>jruby-stdlib</artifactId>
        </exclusion>
        <exclusion>
          <groupId>me.n4u.sass</groupId>
          <artifactId>sass-gems</artifactId>
        </exclusion>
        <exclusion>
          <groupId>nz.co.edmi</groupId>
          <artifactId>bourbon-gem-jar</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.codehaus.gmaven.runtime</groupId>
          <artifactId>gmaven-runtime-1.7</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.webjars</groupId>
          <artifactId>jshint</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.webjars</groupId>
          <artifactId>emberjs</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.webjars</groupId>
          <artifactId>handlebars</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.webjars</groupId>
          <artifactId>coffee-script</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.webjars</groupId>
          <artifactId>jslint</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.webjars</groupId>
          <artifactId>json2</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.webjars</groupId>
          <artifactId>jquery</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
  </dependencies>
</plugin>

The dependencies to wro4j-core and wro4j-extensions are needed by jetty, to be able to enable the filter defined below. Unfortunatly, one of the transitive dependencies of wro4j-extensions triggers an uggly error when running the jetty-maven-plugin. Therefore, all unneeded dependencies of wro4j-extensions are excluded, as a workaround for this error/bug.

jetty-web.xml

And my jetty-web.xml looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
  version="2.5">
  <filter>
    <filter-name>wro</filter-name>
    <filter-class>ro.isdc.wro.http.WroFilter</filter-class>
  </filter>
  <filter-mapping>
    <filter-name>wro</filter-name>
    <url-pattern>*.css</url-pattern>
  </filter-mapping>
</web-app>

The filter processes any URI’s that end with .css. This way, the wro4j servlet-filter makes base.css available under any path, because for exampl /base.css, /css/base.css and /foo/bar/base.css all end with .css.

This is all, that is needed to develop with dynamically reloadable compiled LESS-resources. Just fire up your browser and browse to /what/you/like/base.css. (But do not forget to put some LESS-files in src/main/webapp/less/base/ first!)

Step 3: Install wro4j-maven-plugin

All that is left over to configure now, is the build-process. If you would build and deploy your webapp now, the CSS-file base.css would not be generated and the link to your stylesheet, that already works in our jetty-maven-plugin environment would point to a 404. Hence, we need to set up the wro4j-maven-plugin. I am using this configuration:

<plugin>
  <groupId>ro.isdc.wro4j</groupId>
  <artifactId>wro4j-maven-plugin</artifactId>
  <version>${wro4j.version}</version>
  <configuration>
    <wroManagerFactory>ro.isdc.wro.maven.plugin.manager.factory.ConfigurableWroManagerFactory</wroManagerFactory>
    <cssDestinationFolder>${project.build.directory}/${project.build.finalName}/css/</cssDestinationFolder>
  </configuration>
  <executions>
    <execution>
      <phase>prepare-package</phase>
      <goals>
        <goal>run</goal>
      </goals>
    </execution>
  </executions>
</plugin>

I connected the run-goal with the package-phase, because the statically compiled CSS-file is needed only in the final war. The ConfigurableWroManagerFactory tells wro4j, that it should look up further configuration options in our wro.properties-file, where we tell wro4j, that it should compile our LESS-resources. The <cssDestinationFolder>-tag tells wro4j, where it should put the generated CSS-file. You can adjust that to suite your needs.

That’s it: now the same CSS-file, which is created on the fly by the wro4j servlet-filter when using mvn jetty:run and, thus, enables dynamic reloading of our LESS-resources, is generated during the build-process by the wro4j-maven-plugin.

Cleanup and further considerations

lesscss-maven-plugin

If you already compile your LESS-resources with the lesscss-maven-plugin, you can stick with it and skip step 3. But I strongly recommend giving wro4j-maven-plugin a try, because it is a much more powerfull tool, that can speed up your final webapp even more.

Clean up your mess

With a configuration like the above one, your LESS-resources and wro4j-configuration-files will be packed into your production-war. That might be confusing later, because neither wro4j nor LESS is used in the final war. You can add the following to your pom.xml to exclude these files from your war for the sake of clarity:

<plugin>
  <artifactId>maven-war-plugin</artifactId>
  <configuration>
    <warSourceExcludes>
      WEB-INF/wro.*,
      less/**
    </warSourceExcludes>
  </configuration>
</plugin>

What’s next?

We only scrached the surface, of what can be done with wro4j. Based on this configuration, you can easily enable additional features to fine-tune your final build for maximum speed. You really should take a look at the list of available Processors!