Thomas Toye bio photo

Thomas Toye

Student interested in web development, scalability and hiking. Currently studying NCMT at Howest.

Twitter Facebook Google+ Github

Making Bootstrap 3.1.x play nicely with Play Framework 2.2.x

Bootstrap is a nice CSS framework and it can really help you when you need something quick. I recently started working with the Play framework and wanted to use the latest version of Bootstrap. Here’s how to get it working.

Assumptions

I’m going to assume you installed the Play Framework (most versions in the 2.x range will be similar, but I’m going to use version 2.2.2).

The version of Bootstrap we’re going to install is 3.1.1, but as you’ll see, using other versions or even upgrading a Bootstrap version is as easy as changing a number.

Bootstrap WebJar

WebJars are client-side packages (such as Bootstrap or jQuery) that are packaged in JAR files for easy management.

Adding a WebJar to Play

sbt is the build tool for Play. We can add WebJars to our build.sbt. sbt will read this file and use Apache Maven to fetch the dependencies specified (including our WebJars).

First off all, add the following line to your build.sbt:

1 "org.webjars" %% "webjars-play" % "2.2.1-2",

Let’s go to the WebJars homepage. Scroll down and find bootstrap (or any other package you like), it will have an entry like this:

1 "org.webjars" % "bootstrap" % "3.1.1-1"

Add this to your build.sbt.

Here’s a sample build.sbt:

 1 name := "My Cool Test Site"
 2 
 3 version := "1.0-SNAPSHOT"
 4 
 5 libraryDependencies ++= Seq(
 6   javaJdbc,
 7   javaEbean,
 8   cache,
 9   "org.webjars" %% "webjars-play" % "2.2.1-2",
10   "org.webjars" % "bootstrap" % "3.1.1"
11 )
12 play.Project.playJavaSettings

Now do go in the Play console, do clean, then run. Play will re-fetch all dependencies.

Adding a route for the WebJar

Add the following to your conf/routes:

1 # WebJar routing (for bootstrap, ...)
2 GET		/webjars/*file					controllers.WebJarAssets.at(file)

Referencing Bootstrap from your views

You can use @routes.WebJarAssets.at(WebJarAssets.locate("...")) to reference a file from your views. We can find a list of files that are included

A list of files that are included in the Bootstrap 3.1.1-1 WebJar.

To reference the file css/bootstrap.min.css, we can use @routes.WebJarAssets.at(WebJarAssets.locate("css/bootstrap.min.css")).

Styling forms

Styling forms is hard because we can’t use the default input helpers. Luckily, Play provides a Bootstrap helper… which hasn’t been updated in 2 years. It’s still usable, but it was created for Bootstrap 2.x, which had different class names for forms.

Writing a custom FieldConstructor

We’re going to write our own field constructor now so we don’t have to write lots of boiler-plate code for each form input.

Make a new file called bootstrapFieldConstructorTemplate.scala.html in app/views and add the following:

1 @(elements: helper.FieldElements)
2 <div class="form-group @if(elements.hasErrors) {has-error}">
3   <label for="@elements.id" class="control-label">@elements.label</label>
4   @elements.input
5   <span class="help-block">@elements.infos.mkString(", ")</span>
6   <span class="help-block">@elements.errors.mkString(", ")</span>
7 </div>

Using the FieldConstructor

In your view, import the following:

1 @import helper._
2 @implicitField = @{ FieldConstructor(bootstrapFieldConstructorTemplate.f) }

Now, when you use something like @helper.inputText(orderForm("id")), Play will use the field constructor you specified.

The final touch

The only thing left to do is to add the form-control class on the <input> tag. We can do that like this:

1 @helper.inputText(orderForm("id"), 'class -> "form-control")

Here’s the final view:

 1 @(orderForm: Form[Order])
 2 @import helper._
 3 
 4 @implicitField = @{ FieldConstructor(bootstrapFieldConstructorTemplate.f) }
 5 
 6 <h2>A form</h2>
 7 
 8 @helper.form(action = routes.Application.index()) {
 9   @helper.inputText(orderForm("id"), 'class -> "form-control")
10 }

Github repo

The code for this article is available as a Github repo over here.

Updating Bootstrap

When a new Bootstrap version comes out, the first thing you’ll want to do is to check the WebJars site. Usually new versions should be available there pretty quick. You can than add the new version number to your build.sbt. After that, do a play clean and a play cleanFiles, then play run. That should work just fine.