Customizing Twitter Bootstrap with the Lesscss Gradle plugin

Abstract

In this article I will show you how to customize the Twitter Bootstrap style sheets and compile them with the Lesscss Gradle plugin.

You won’t have to change the original sources. You won’t even have to download them manually.

I’ll also show how you can inspect the LESS sources in your browser (in stead of the generated CSS) and how to get productive with automatic compilation.

Quick start

1. If you already have gradle:

   There’s only one file to download: build.gradle :)
   Save it in the directory less-bootstrap and then:

   cd less-bootstrap
   gradle init
   gradle lesscDaemon --info

2. You don’t have Gradle yet:

   Clone the github project with git clone https://github.com/houbie/less-bootstrap or download and unpack the zip distribution and use the included gradle wrapper:

   cd less-bootstrap
   gradlew init
   gradlew lesscDaemon --info

Now you can:

1. open less-bootstrap/web/bootstrap-examples/theme/index.html (or an other example)

2. change less-bootstrap/web/less/custom-variables.less

3. reload the page to see the changes

Tip	Before reloading the page in your browser, you’ll have to wait a few seconds until the style sheets are compiled. If you don’t like waiting (who does?), see Speeding up compilation

Exploring the examples

The examples are located in less-bootstrap/web/bootstrap-examples. When you open f.e. less-bootstrap/web/bootstrap-examples/theme/index.html and inspect the Learn more button in Google Chrome, you will see something like this:

Figure 1. Inspecting an element in Chrome

The inspector shows the LESS sources because the the lessc task is configured to generate source maps:

Enabling source maps in build.gradle

lessc {
    ...

    //generate source maps so that Google Chrome shows the less source in the inspector i.s.o. the raw CSS
    options.sourceMap = true

    //the generated css file contains a reference to the source map, this reference will be relative to
    //the sourceMapBasepath in this case it will be in the same directory as the css itself
    //(default location of source maps)
    options.sourceMapBasepath = file("$webDir/css").absolutePath

    //we could try to specify the sourceMapxxx options so that the browser can load the LESS sources
    //directly, but this is not trivial since our sources reside in different locations
    //therefore we just copy all the less source code into the source map file
    options.sourceMapLessInline = true

}

Note	At the moment of writing, Chrome is the only browser that supports source maps for CSS files. This blog shows how to enable CSS source maps if they are not enabled by default.

Customizing the style sheet

Where is the code?

We would like to change the background color of the Learn more button, but how do we locate its definition?

Again, by inspecting the element in Chrome, we see that the background color is defined in buttons.less.

Figure 2. The button’s background colour

When we double-click buttons.less, the source is opened in the inspector:

Figure 3. Buttons.less

We see that the variable that we need to change is btn-primary-bg. Unfortunately, we cannot navigate further anymore in the inspector, so we have to search manually.

The bootstrap source files can be found in less-bootstrap/build/bootstrap/web-app/less. A text search leads us to mixins.less for the button-variant definition and to variables.less for the background color variable:

@btn-primary-bg: @brand-primary;

Albeit not perfect, it is a lot easier to find the code in this way than if we would only see the raw CSS in the inspector.

At this point we have to decide whether we want to change only the color of the primary buttons, or if we want to change the primary brand color.

Modifying styles

There are 3 ways to modify the style sheets:

1. Overwrite variables in build.gradle

2. Modify a copy of the original source

3. Create our own customization LESS file

Overwriting variables in build.gradle

The lesscss compiler allows us to declare new or overwrite existing variables via the commandline or in build.gradle:

lessc {
    ...
    options.modifyVars = ['brand-primary': 'purple']
}

Overwriting variables this way can be useful if you want f.e. to use a different color scheme for development builds than for release builds, but it is not suitable for more involved customizations.

Modify a copy of the original source

The lessc task is configured to lookup LESS files first in less-bootstrap/web/less:

lessc {
    ...
    sourceDir "$webDir/less", "$buildDir/bootstrap/web-app/less"
}

This means that if we would copy variables.less to less-bootstrap/web/less and modify it, it will take precedence over the original file.

However, when we would like to upgrade to a newer bootstrap version, we would need to apply all our changes again in the new file, which is far from ideal.

Note	Changing brand-primary in our copy of variables.less won’t have any effect, it will always be overridden by the value in build.gradle!

Create our own customization LESS file

The main LESS file, bootstrap.less, consists of only import statements. If we would append a few import statements to include our own customization files, we wouldn’t have to change the original LESS code. This is exactly what the init task does when it unpacks the bootstrap sources:

//have our custom less files imported into bootstrap.less and theme.less
file("$buildDir/bootstrap/web-app/less/bootstrap.less").text += '''
@import "custom-variables.less";
@import "application.less";'''

file("$buildDir/bootstrap/web-app/less/theme.less").text += '@import "custom-variables.less";'

Now you only have to keep the customizations in your project’s source repository. Furthermore, switching to another version of bootstrap becomes trivial.

Define your own semantics

As pointed out in this blog, you should use html elements and/or CSS classes that outline the structure of your documents.

/less-bootstrap/web/less/application.less defines a sample article structure that is used in less-bootstrap/web/bootstrap-examples/starter-template/semantics.html.

Again, we are extending bootstrap without changing the original sources.

Speeding up compilation

Although the lesscss compiler is the fastest Java LESS compiler, it is still very slow compared with the original node.js compiler.

Fortunately, you can use the node.js lessc compiler in combination with the Lesscss Gradle Plugin:

lesscDaemon {
    engine = 'commandline'
    lessExecutable = '/opt/local/bin/lessc'
}

Now, your style sheets will typically be compiled by the time you switched from the source editor to the browser.

The lessExecutable is only required when lessc is not on your path. In windows you should include the .bat or .cmd extension.

You can read here how to install the node.js lessc compiler.

Tip	Use the fast node.js compiler in the lesscDaemon task to save time when developing the style sheets. Keep the default (java rhino based) compiler in the lessc task to avoid installing node.js on your CI server and to have deterministic builds that always use the same compiler version.

Resources

Twitter Bootstrap	http://getbootstrap.com/
LESS	http://lesscss.org
Lesscss	https://github.com/houbie/lesscss
Lesscss gradle plugin	https://github.com/houbie/lesscss-gradle-plugin
Gradle	http://gradle.org

Follow-up: JavaScript on the JVM, experimenting with Nashorn

The release of JDK8 was a good opportunity to test again how fast the Nashorn JavaScript engine is in compiling Less style sheets.
I hoped that performance improved since I last tried an early access build, but alas...

Setup

I recently released a new version of lesscss that supports 3 execution engines:

• rhino 1.7R4: it runs a pre-compiled version of less.js in the highest optimization level (9)
• nashorn: the JDK8 built-in version, which does not (yet) support pre-compilation nor optimization
• node.js lessc: prepare a commandline string and execute it with Runtime.exec

I compiled the Twitter Bootstrap style sheets using different engines.
I used my mac book (2.66GHz core i7 with 8GB memory and JVM args -Xms512m -Xmx1500m -XX:MaxPermSize=320m).
For each run I instantiated one engine for 15 consecutive compilations.

As you can see, both rhino and nashorn perform better when the JVM warmed up, but the differences in performance are huge:

Time needed to compile Twitter Bootstrap (seconds)
  The first row includes JavaScript compilation in case of Nashorn

#	Rhino (optimized)	Nashorn	node.js
1	3.9	18.4	0.9
2	1.9	7.9	0.6
3	1.7	6.1	0.6
4	1.6	5.8	0.6
5	1.4	5.0	0.6
6	1.4	4.9	0.6
7	1.5	4.5	0.6
8	1.4	5.3	0.6
9	1.3	5.8	0.6
10	1.3	4.4	0.6
11	1.0	4.0	0.6
12	1.0	3.8	0.6
13	1.0	3.5	0.6
14	0.9	3.1	0.6
15	0.9	2.8	0.6

Conclusions

Although this is not a real benchmark, the figures differed less then 20% between runs and the trends are clear (at least for this use case):

• Rhino with optimizations is still a lot faster then nashorn
• While rhino got faster on JDK8, nashorn seems to got slower (see previous blog)
• There is a big gap with node.js, despite the overhead of spawning a new process and writing its output to disk

Open source releases: a piece of Gradle

Yennick Trevels wrote a great blog on how to set up a Gradle build to deploy to the Sonatype OSS Repository (and from there to maven central).
Here I will show how the Gradle release plugin can be configured to

• streamline the release process
• automatically provide download links to you latest release on Github

The standard release process

The principles of the Gradle release plugin originate from the Maven release plugin. The release steps are:

• check release preconditions (no uncommitted files and no snapshot dependencies)
• get the release version number
• build (and test) the release
• tag the release
• update the version number and commit it

Configuration

Add the build dependency and apply the plugin:

buildscript {
    dependencies {
        classpath 'com.github.townsfolk:gradle-release:1.2'
  ...
    }
 ...
}

apply plugin: 'release'

The release plugin is not fully documented, but fortunately it is small and the code speaks for itself (its Gradle :)
In ReleasePluginConvention.groovy you find all the properties that can be specified. I changed the default versionPropertyFile (gradle.properties) to versions.txt, to make it obvious to find the project version. You can also see how to use complex version schemes.

release {
    versionPropertyFile = 'version.txt'

    //a map of [regular expression : increment closure],
    //if the version matches one of the regexps, the corresponding
    // closure is used to auto-increment the version
    versionPatterns = [
            // 1.2.3-groovy-1.8.4 -> next version: 1.2.4-groovy-1.8.4
            /(\d+)-groovy-(.+$)/: {matcher, project ->
                matcher.replaceAll("${(matcher[0][1] as int) + 1}-less-${matcher[0][2]}")
            }
    ]
}

The version needs to be read from the file:

//the release plugin expects the content to be 'version=xyz',
//without whitespace around the =
version = file('version.txt').text.split('=')[1].trim()

Build hooks

One of the most powerful features of Gradle is the ability to hook custom tasks about anywhere in the build cycle.
gradle tasks --all shows all the steps in the release task that we can hook into:

checkCommitNeeded - Checks to see if there are any added, modified, removed, or un-versioned files.
checkSnapshotDependencies - Checks to see if your project has any SNAPSHOT dependencies.
checkUpdateNeeded - Checks to see if there are any incoming or outgoing changes that haven't been applied locally.
commitNewVersion - Commits the version update to your SCM
confirmReleaseVersion - Prompts user for this release version. Allows for alpha or pre releases.
createReleaseTag - Creates a tag in SCM for the current (un-snapshotted) version. [uploadArchives]
initScmPlugin - Initializes the SCM plugin (based on hidden directories in your project's directory)
preTagCommit - Commits any changes made by the Release plugin - eg. If the unSnapshotVersion tas was executed
release - Verify project, release, and update version to next. [clean]
unSnapshotVersion - Removes "-SNAPSHOT" from your project's current version.
updateVersion - Prompts user for the next version. Does it's best to supply a smart default.

Hooking in is straightforward:

//always clean before building a release
release.dependsOn clean
//upload to sonatype before tagging the VCS
createReleaseTag.dependsOn uploadArchives

We should only upload release builds to the sonatype staging repository, so we tweak the 'uploadArchives' a little bit:

task uploadSnapshot(dependsOn: uploadArchives)

// the release task spawns a new GradleBuild that doesn't contain
// release itself, but it contains createReleaseTag
def sonatypeRelease = gradle.startParameter.taskNames.contains('createReleaseTag')
def sonatypeSnapshot = gradle.startParameter.taskNames.contains('uploadSnapshot')
if (sonatypeRelease) {
    //only sign releases
    signing {
        sign configurations.archives
    }
}
def sonatypeRepositoryUrl = sonatypeRelease ?
    'https://oss.sonatype.org/service/local/staging/deploy/maven2/' :
    'https://oss.sonatype.org/content/repositories/snapshots/'

uploadArchives {
    repositories {
        if (!(sonatypeRelease || sonatypeSnapshot)) {
            mavenLocal()
        } else {
            mavenDeployer {
                if (sonatypeRelease) {
                    beforeDeployment { deployment -> signing.signPom(deployment) }
                }

                repository(url: sonatypeRepositoryUrl) {
                    authentication(userName: sonatypeUsername,
                    password: sonatypePassword)
                }

                pom.project {
...

Provide download links

In the README.md we can include links to our artifacts on maven central:

You can download coolapp from the [maven central repository]
 (http://central.maven.org/maven2/org/awesome/coolapp/1.2.3-groovy-1.8.4/coolapp-1.2.3-groovy-1.8.4.zip)

With a few extra lines of Groovy, we can make the links point to the new release. The modified README can be committed to Github together with the new snapshot version:

task updateReadme << {
    File readme = file('README.md')
    //the release version is the version before the release minus 'SNAPSHOT'
    def releaseVersion = "${project['release.oldVersion']}".replaceAll('-SNAPSHOT', '')
    //replace all occurrences of x.y.z-groovy-a.b.c with the new release version
    readme.text = (readme.text =~ /\d\.\d(\.\d)?-groovy-\d\.\d(\.\d)?(-SNAPSHOT)?/)
                                                     .replaceAll("${releaseVersion}")
}

commitNewVersion.dependsOn updateReadme

And that's all there is to it. A working example can be found in the lesscss project.

Spock framework: writing tests at warp speed

Groovy  is a superb language for automated tests: it is far more powerful than Java and it allows to skip lots of boilerplate code. The Spock framework adds a nice test specification DSL on top of that. In this post, you will find out more about my favorite Spock feature: data driven testing.

Write one test and get 40 for free

I build a Java port of the LESS CSS compiler, originally written in JavaScript.
The LESS compiler already has more than 40 test cases that compare a compiled LESS file with the expected CSS result. I only had to create one unit test that loops over all LESS files, compiles them and checks the result.

def "less compatibility tests"() {
    expect:
    compiler.compile(lessFile) == getCss(lessFile)

    where:
    lessFile << new File('test/less').listFiles().findAll { it.name.endsWith('.less') }
}

def getCss(File lessFile) {
   return new File('test/css' + lessFile.getName().replace('.less', '.css')).text
}

Notice how you can tell Spock that it has to create one test for each variable in a collection:

where:
variable << collection

Also notice the absence of assertEquals in the expect block: we only need to write boolean conditions. As programmers (and even non-programmers), we are trained to recognize these comparisons, so they are easier to read, understand and maintain then the classical assertXxx method calls.

Test isolation

We could also write a plain JUnit test that loops over the files to test them, but the problem would then be test isolation: if one test fails, the test method is aborted and we won't know the status of the remaining tests.
Spock, instead, runs an isolated test for each iteration. All failures are reported separately, but if all tests pass, you will see only one method in the test report.
In the above example, it would be even better to have one test method with a descriptive name for each LESS file. This is what Spock's Unroll annotation does:

@Unroll
def "#lessFile.name compatibility test"() {...}

By using #lessFile.name in the method name, we get clear test reports:

Data tables

Spock where blocks are not limited to one variable. If you want to populate more than one variable in each iteration, you can use the collection approach as shown above, or you can provide a table with values:

when:
def reader = new FileSystemResourceReader()

then:
reader.canRead(location) == canRead

where:
location       | canRead
'file1.txt'    | true
'../file2.txt' | true
'/no file'     | false

This example will run 3 tests: one for each data row.
Data tables are especially useful for testing the typical use cases and corner cases in one go.
Syntactically, a data table is a bunch of unrelated or statements, so it may look strange at first sight. But if well formatted, data tables look like tables, and that's how Spock interprets them.
Intellij IDEA users get an extra here: it knows about Spock data tables and can format them automatically.

Links

The full examples are part of the Lesscss project at GitHub. Feel free to post any comments or suggestions.

JavaScript on the JVM: experimenting with Nashorn

I recently experimented with the upcoming Nashorn JavaScript run-time to compile Less style sheets.
I hoped to boost the performance in comparison with existing Less compilers for the JVM, but the results where not what I expected...

Motivation

Although I am a fan of Twitter Bootstrap and Less CSS in general, I found that the Less compilation in Java projects could take several seconds and thus be really bad for development turnaround.
During Devoxx 2012, Marcus Lagergren explained how much faster Nashorn was compared with Rhino (being already included in the standard Java distribution). So I took it for a test drive.

Can't wait for Java 8

 I didn't have JDK8 installed yet, so I forked a backport on GitHub and build the nashorn.jar that provides a standard javax.script.ScriptEngine implementation.
This made it easy to support both Rhino and Nashorn: by specifying -Djava.ext.dirs=/path/to/nashorn, Nashorn was used by default with a fallback to Rhino.

ScriptEngineManager factory = new ScriptEngineManager();
ScriptEngine scriptEngine = factory.getEngineByName("nashorn");
if (scriptEngine == null) {
    scriptEngine = factory.getEngineByName("nashorn");
}
if (scriptEngine == null) {
    throw new RuntimeException("No JavaScript script engine found");
}

The compiler

I didn't use the Rhino specific less script, but instead used the standard less-1.3.3.js. I only had to add a few lines of JavaScript in front, to stub a little browser functionality, and add a compile function at the back to be called from Java.
The Java code was rather simple:

scriptEngine.eval(getLessScriptReader());
String css =
   ((Invocable) scriptEngine).invokeFunction("compile", lessString);

The Bootstrap test

The Twitter Bootstrap style sheets compiled successfully with both Rhino and Nashorn
Compilation with Rhino took 10 seconds on my Macbook, while Nashorn did in in 8 seconds. Not exactly impressive...
To get an idea of the JavaScript compilation / execution ratio , I invoked the Less compile function multiple times, hereby reusing the JavaScript context.

Time needed to compile Twitter Bootstrap (seconds)
  The first row includes JavaScript compilation

#	Rhino	Rhino (optimized)	Nashorn JDK7	Nashorn JDK8
1	9.8	5.5	8.0	15.0
2	7.5	2.1	2.5	5.8
3	7.3	1.5	/	3.7
4	7.4	1.1	/	3.4
5	7.3	1.0	/	3.4

The first column is for Rhino invoked as described above using the javax.script interfaces. By default Rhino always runs in interpreted mode. Compare this with the second column, where the Rhino Context is used directly which allows to set the optimization level to 9 (highest level).
The third column is for Nashorn on Java 7. The Nashorn backport apparently contains some bugs, causing the third Less compilation within the same JavaScript context to fail.
The fourth column contains the results of the Less compilation using a JDK8 snapshot. The engine now works correctly, but the performance still needs to improve a lot.

Conclusions

I realize that the Nashorn project is still in alpha, but until the team comes up with an API that allows compiler optimizations like Rhino does, the latter still seems to be the best bet.