Content of Play Framework

by Sebastian

Play is a Web Framework for Scala and Java and it is a really powerful and complete one. It provides an easy way of building web servers, running on an embedded jetty, and even rest clients with its WS library.

In this example, we are going to get a Play Application running. We’ll see how to create it from scratch using typesafe activator 1.2.12, sbt 0.13.5, java 1.8.0_66, scala 2.11.6 and Play 2.4.3. We’ll learn how to create Actions, how does routing work in play and we’ll see its very powerful template engine in action.

We are using activator because it makes it easier to start a project from scratch. It provides a few project templates, including play with scala, play with java, akka and mongodb, among others.

1. Creating the Project

So we run:

And we’ll see something like:

For now we’ll choose 6) play-scala for scala or 5) play-java for java, as you wish.

It will ask for the name of your application, play-example will work for us now, so we type it and hit enter.

After a little while we’ll see it’s done and we can cd play-example && ll to see what it did:

This output should be the same for both languages. As you can see, it created two binaries (activator and activator.bat) and a jar, these are created by activator, so if you want to contribute to this application from a computer which hasn’t activator installed, yo can do it anyway, but we will just delete them.

It also created a few directories: app, conf, project, public and test, which we’ll explain one by one soon enough.

There is also a build.sbt, which holds the build definition for sbt.

2. Directory Structure

2.1. The server side source directory: app

This directory holds all the server side source code and play templates. As we can see, activator created, inside of this directory, two packages: controllers and views.

In the controllers directory, there is already an Application, which is an example controller generated by activator. Let’s take a look to both java and scala examples:

Application.java

Application.scala

In play, the handler of an HTTP request is called an Action, which holds a method that receives a request and returns a result, and this class defines one called index, which returns Ok with some HTML generated by play’s template engine. It is calling a template called index, located in views.html, with a String as parameter, so we get back and go to the views package and hit ll. We’ll see:

As you can see, there is no html package here, that’s because, on compilation, play creates that package with these templates compiled as scala classes. That means you can write scala code inside these templates. Let’s check out index.scala.html for it is the one being called from our index action.

index.scala.html

Play templates are written in scala, but this should not be a problem for java developers, as you should never write complex logic in templates. Most of the time you will just access data from your model objects.

The first line defines the constructor, as @(parameter1Name: Parameter1Type, ..., parameterNName: ParameterNType), receiving a String, which is consistent with what we saw in our index action.

The second line is making a call to main template, which is in the same package, and passes a string as a parameter. But also, there is some code between the curly braces. The curly braces, in that context, define a piece of HTML to be returned. Inside them, @play20.welcome is being called, which is a play function that returns a welcome page with some message, given as a parameter, as heading.

So, let’s take a look at that main template.

main.scala.html

Here, we see a constructor that defines two parameters: title and content. We are already familiar with values of type String, so just check out the title tag. Inside you see @title, and that’s how you render a value in a template. Also, inside the body tag, this template is rendering content. Strings, Ints, Booleans and Html are rendered almost seamlessly in play templates.

Also, check out the header for those links and the script. It’s using @routes.Assets.versioned to get those sources. I’ll get back to it later.

So here it is, a full HTML that’s going to be rendered when an HTTP request is done to our index action. So, where does that routing thingy happen?

2.2. The configuration directory: conf

From now on, it doesn’t matter if you are working with java or scala. Everything from here is common to all play applications.

Now we switch to that conf directory and ll.

The activator created an application.conf, which holds general configuration properties (db connections, service endpoints, etc.), logback.xml, logback’s logging configuration, and routes, and there are our endpoints defined. Check it out.

routes

We need to see it as a three columns table, where the first one represents the http action (GET, POST, PUT, DELETE, HEAD, OPTIONS), the second one represents the path and the third one represents our bound action.

The first defined route is our index. You can read it like: All GET requests to / are handled by controllers.Application.index.

The second route lets us get back to that @routes.Assets.versioned in our main template. It is mapping all GET requests to /assets/* to controllers.Assets.versioned. Which receives a path, hardcoded with the value "/public" (this parameter is telling play where is the static content located in our project), and an Asset, which is a route to a file given as parameter in the url.

2.3. The static content directory: public

If you switch to this directory, you’ll see three other ones: images, javascripts and stylesheets. And as we’ve seen in our routes file, controllers.Assets.versioned is configured to serve static content from here. Inside these folders you will find some basic examples. A javascript file, a css file and an image (favicon).

So, what’s happening in our templates when we invoke @routes.Assets.versioned? In play this is called reverse routing. In the routes package, you will find references to every controller in your project, which hold URL builders of every defined action. So when you call @routes.Assets.versioned with the path to a file relative to "/public", it will render the absolute URL to that file. And this works for every action, parametrized or not.

2.4.The project directory: project

This directory should hold only sbt configuration files, such as build.properties, which defines sbt’s version, and plugins.sbt, which imports needed plugins.

Play has its own sbt plugin, com.typesafe.play:sbt-plugin, which is necessary for every play application, as a lot of play’s magic happens on compilation. It defines and overrides a lot of goals, such as run, clean and compile.

3. Running the application

Change to project’s root directory and run:

After it’s done resolving its dependencies and compiling the project you will see something like:

And when that’s printed out, your server is up and running. By default, it will be listening at http://localhost:9000/, check it out and you should see something like:

Play Scala App

4. Download the Code Project

This was a tutorial on the basics of play framework.

Download
You can download the full source code of this example here: play-scala-example, play-java-example