Fr

ee

Play Framework is an open source web application

framework that is written in Java and Scala. It follows the
Model-View-Controller architectural pattern and enables
the user to employ Scala for application development,
while keeping key properties and features of Play
Framework intact.
Starting off by building a basic application with minimal
features, you get a detailed insight into handling data
transactions and designing models in Play. Next, you
venture into the concepts of Actors and WebSockets,
the process of manipulating data streams, and testing
and debugging an application in Play. Finally, you gain
an insight into extending the framework by writing
custom modules or plugins in Play. Each chapter has
a troubleshooting section that helps you out by
discussing the causes of, and solutions to, some commonly
faced issues.

What you will learn from this book

Customize your framework to accommodate
the specific requirements of an application
Develop responsive, reliable, and
highly scalable applications using
Play Framework
Build and customize Play Framework
plugins that can be used in multiple
Play applications
Familiarize yourself with third-party APIs to
avoid rewriting existing code
Gain an insight into the various aspects of
testing and debugging in Play to successfully
test your apps

Mastering Play Framework for Scala

Mastering Play Framework

for Scala

Who this book is written for

Get to know all about the concepts of
WebSockets and Actors to process
messages based on events

$ 49.99 US
32.99 UK

community experience distilled

P U B L I S H I N G

Shiti Saxena

This book is intended for those developers who are keen

to master the internal workings of Play Framework to
effectively build and deploy web-related apps.

pl

C o m m u n i t y

E x p e r i e n c e

D i s t i l l e d

Mastering Play Framework

for Scala
Leverage the awesome features of Play Framework to build
scalable, resilient, and responsive applications

Prices do not include

local sales tax or VAT
where applicable

Visit www.PacktPub.com for books, eBooks,

code, downloads, and PacktLib.

Sa
m

Shiti Saxena

In this package, you will find:

The author biography

A preview chapter from the book, Chapter 1 'Getting Started with Play'
A synopsis of the books content
More information on Mastering Play Framework for Scala

About the Author

Shiti Saxena is a software engineer with around 4 years of work experience. She
is currently working with Imaginea (a business unit of Pramati). She has previously
worked with Tata Consultancy Services Ltd. and Genpact.
A true polyglot, she's had exposure to various languages, including Scala, JavaScript,
Java, Python, Perl, and C. She likes to work with Play Scala and AngularJS.
She blogs at
projects on GitHub.

and maintains open source

She loves to travel, is a movie buff, and likes to spend time playing her piano whenever
she is not programming.
She has authored Getting Started with SBT for Scala

Mastering Play Framework for Scala

The Play Framework is an open source web application framework that is written in Java
and Scala. It follows the Model-View-Controller architectural pattern.
It enables the user to use Scala for application development, keeping key properties and
features of the Play Framework intact. This results in faster and scalable web apps. Also,
it uses a more functional and "Scala idiomatic" style of programming, without sacrificing
simplicity and developer friendliness.
This book will provide advanced information on developing Scala web applications using
the Play Framework. This will help Scala web developers master Play 2.0 and use it for
pro-Scala web app development.

What This Book Covers

Chapter 1, Getting Started with Play, explains how to build simple applications using
the Play Framework. We also explore the project structure so that you can understand
how the framework plugs in the required settings through a build file.
Chapter 2, Defining Actions, explains how we can define an application-specific action
with default parsers and results, and also with custom parsers and results.
Chapter 3, Building Routes, is where we see how essential routing is in a Play
application. Apart from this, we also check out various default methods that Play
provides for simplifying the process of routing.
Chapter 4, Exploring Views, explains how to create views using Twirl and the various
other helper methods provided by Play. In this chapter, you also learn how you can
support multiple languages in your Play application using the built-in i18n API.
Chapter 5, Working with Data, demonstrates different ways of causing application data
to persist in an application that we build using the Play Framework. In addition to this,
you also get to understand how the Play Cache API can be used and how it works.
Chapter 6, Reactive Data Streams, discusses the concepts of Iteratee, Enumerator,
and Enumeratee and how they can be implemented in the Play Framework and
used internally.
Chapter 7, Playing with Globals, gives an insight into the features provided for a Play
application through the global plugin. We also discuss hooks for the request-response life
cycle, using which we can intercept requests and responses and modify them if required.
Chapter 8, WebSockets and Actors, briefly covers the Actor Model and the usage of Akka
Actors in an application. We also define a WebSocket connection in a Play application
with various constraints and requirements, using different approaches.

Chapter 9, Testing, shows you how a Play application can be tested using Specs2 and
ScalaTest. We go through the different helper methods available for simplifying testing
of a Play application.
Chapter 10, Debugging and Logging, is where we configure the debugging of a Play
application in the IDE. In this chapter, you get to learn how to start a Play application in
the Scala console. This chapter also places emphasis on the logging API provided by the
Play Framework and the methods of customizing the log format.
Chapter 11, Web Services and Authentication, explains the WS (WebService) plugin and
the API exposed through it. We also access users' data from the service providers using
OpenID and OAuth 1.0a.
Chapter 12, Play in Production, explains how to deploy a Play application on production.
While deploying the application, we also check the different packaging options (RPM,
Debian, ZIP, Windows, and so on) available by default.
Chapter 13, Writing Play Plugins, gives an explanation of all plugins, with their
declaration, definition, and best practices.

Getting Started with Play

The World Wide Web has grown by leaps and bounds since its first appearance in
August 1991. It has come a long way from line mode browsers and static websites to
graphical browsers and highly interactive websites, such as search engines, online
department stores, social networking, gaming, and so on.
Complex websites or applications are backed by one or more databases and several
lines of code. In most cases, such web applications use a framework to simplify the
development process. A framework provides a skeleton structure that handles most
of the repetitive or common features. Ruby on Rails, Django, Grails, and Play are a
few examples of this.
Play Framework was developed by Guillaume Bort while he was working at
Zenexity (now Zengularity). Its first full release was in October 2009 for version 1.0.
In 2011, Sadek Drobi joined Guillaume Bort to develop Play 2.0, which was adopted
by Typesafe Stack 2.0. Play 2.0 was released on March 13, 2012.
In this chapter, we will be covering the following topics:

The reasons for choosing Play

Creating a sample Play application

Creating a TaskTracker application

Venturing into the world of Play

Play's installation is hassle free. If you have Java JDK 6 or a later version, all you
need to do to get Play working is an installation of Typesafe Activator or Simple
Build Tool (SBT).

[1]

Getting Started with Play

Play is fully RESTful! Representational State Transfer (REST) is an architectural

style, which relies on a stateless, client-server, and cache-enabled communication
protocol. It's a lightweight alternative to mechanisms such as Remote Procedure
Calls (RPC) and web services (which include SOAP, WSDL, and so on). Here
stateless means that the client state data is not stored on the server and every request
should include all the data required for the server to process it successfully. The
server does not rely on previous data to process the current request. The clients
store their session state and the servers can service many more clients in a stateless
fashion. The Play build system uses Simple Build Tool (SBT), which is a build tool
used for Scala and Java. It also has a plugin to allow native compilation of C and
C++. SBT uses incremental recompilation to reduce the compilation time and can be
run in triggered execution mode, which means that if specified by the user, required
tasks will be run whenever the user saves changes in any of the source files. This
feature in particular has been leveraged by the Play Framework so that developers
need not redeploy after every change in development stage. This means that if a Play
app is running from source on your local machine and you edit its code, you can
view the updated app just by reloading the app in the browser.
It provides a default test framework along with helpers and application stubs to
simplify both unit and functional testing of the application. Specs2 is the default
testing framework used in Play.
Play comes with a Scala-based template engine, due to which it is possible to
use Scala objects (String, List, Map, Int, user-defined objects, and so on) in the
templates. This was not possible prior to 2.0 because earlier versions of Play relied
on Groovy for the template engine.
It uses JBoss Netty as the default web server but any Play 2 application can be
packaged as a WAR file and deployed on Servlet 2.5, 3.0, and 3.1 containers, if
required. There is a plugin called play2-war-plugin (it can be found at https://
github.com/play2war/play2-war-plugin/), which can be used to generate the
WAR file for any given Play2 app.
Play endorses the Model-View-Controller (MVC) pattern. According to the MVC
pattern, the components of an application can be divided into three categories:

Model: This represents application data or activity

View: This is the part of the application which is visible to the end user

Controller: This is responsible for processing input from the end user

[2]

Chapter 1

The pattern also defines how these components are supposed to interact with one
another. Let's consider an online store as our application. In this case, the products,
brands, users, cart, and so on can be represented by a model each. The pages in the
application where users can view the products are defined in the views (HTML
pages). When a user adds a product to the cart, the transaction is handled by a
controller. The view is unaware of the model and the model is unaware of the view.
The controller sends commands to the model and view. The following figure shows
how the models, views, and controllers interact:

Play also comes prepackaged with an easy to use Hibernate layer, and offers
OpenID, Ehcache, and web service integration straight out of the box by adding
a dependency on the individual modules.
In the following sections of this chapter, we'll make a simple app using Play. This is
mainly for developers who are using Play earlier.

A sample Play app

There are two ways of creating a new Play application: Activator, and without
using Activator. It is simpler to create a Play project using Activator since the most
minimalist app would require at least six files.
Typesafe Activator is a tool that can be used to create applications using the Typesafe
stack. It relies on using predefined templates to create new projects. The instructions
for setting up Activator can be found at http://typesafe.com/get-started.

[3]

Getting Started with Play

Building a Play application using Activator

Let's build a new Play application using Activator and a simple template:
$ activator new pathtoNewApp/sampleApp just-play-scala

Then, run the project using the run command:

sampleApp $ sbt run

This starts the application, which is accessible at http://localhost:9000, by default.

The run command starts the project in development mode. In this
mode, the source code of the application is watched for changes,
and if there are any changes the code is recompiled. We can then
make changes to the models, views, or controllers and see them
reflected in the application by reloading the browser.

Take a look at the project structure. It will be similar to the one shown here:

If we can't use Activator, we will probably have to create all these files. Now, let's dig
into the files individually and see which is for what purpose.

The build definition

Let's start with the crucial part of the projectits build definition, and in our
case, the build.sbt file. The .sbt extension comes from the build tool used for
Play applications. We will go through the key concepts of this for anyone who
isn't familiar with SBT. The build definition is essentially a list of keys and their
corresponding values, more or less like assignment statements with the := symbol
acting as the assignment operator.
[4]

Chapter 1

SBT version lower than 0.13.7 expects a new line as the delimiter
between two different statements in the build definition.

The contents of the build file are:

name := "sampleApp"""
version := "1.0.0"
lazy val root = project.in(file(".")).enablePlugins(PlayScala)

In the preceding build definition, the values for the project's name, version, and
root are specified. Another way of specifying values is by updating the existing
ones. We can append to the existing values using the += symbol for individual items
and ++= for sequences. For example:
resolvers += Resolver.sonatypeRepo("snapshots")
scalacOptions ++= Seq("-feature", "-language:reflectiveCalls")

resolvers is the list of URLs from where the dependencies can be picked up and
scalacOptions is the list of parameters passed to the Scala compiler.

Alternatively, an SBT project can also use a .scala build file. The structure for our
application would then be:

[5]

Getting Started with Play

The .scala build definition for SimpleApp will be:

import
import
import
import

sbt._
Keys._
play.Play.autoImport._
PlayKeys._

object ApplicationBuild extends Build {

val appName = "SimpleApp"
val appVersion = "1.0.0"

val appDependencies = Seq(

// Add your project dependencies here
)
val main = Project(appName,
file(".")).enablePlugins(play.PlayScala).settings(
version := appVersion,
libraryDependencies ++= appDependencies
)
}

The .scala build definition comes in handy when we need to define custom tasks/
settings for our application/plugin, since it uses Scala code. The .sbt definition is
generally smaller and simpler than its corresponding .scala definition and is hence,
more preferred.
Without the Play settings, which are imported by enabling the PlayScala plugin,
SBT is clueless that our project is a Play application and is defined according to the
semantics of a Play application.
So, is that statement sufficient for SBT to run a Play app correctly?
No, there is something else as well! SBT allows us to extend build definitions using
plugins. Play-based projects make use of the Play SBT plugin and it is from this
plugin that SBT gets the required settings. In order for SBT to download all the
plugins that our project will be using, they should be added explicitly. This is done
by adding them in plugins.sbt in the projectRoot/project directory.

[6]

Chapter 1

Let's take a look at the plugins.sbt file. The file content will be:
resolvers += "Typesafe repository" at
"http://repo.typesafe.com/typesafe/releases/"
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.3.8")

The parameter passed to addSbtPlugin is the Ivy module ID for the plugin. The
resolver is helpful when the plugin is not hosted on Maven or Typesafe repositories.
The build.properties file is used to specify the SBT version to avoid
incompatibility issues between the same build definitions compiled by using two or
more different versions of SBT.
This covers all the build-related files of a Play application.

The source code

Now, let us look at the source code for our project. Most of the source is in the app
folder. Generally, the model's code is within app/models or app/com/projectName/
models and the controller's source code is in app/controllers or app/com/
projectName/controllers, where com.projectName is the package. The code for
the views should be in app/views or within a subfolder in app/views.
The views/main.scala.html file is the page we will be able to see when we run our
application. If this file is missing, you can add it. If you are wondering why the file is
named main.scala.html and not main.html, this is because it's a Twirl template; it
facilitates using Scala code along with HTML to define views. We will delve deeper
into this in Chapter 4, Exploring Views.
Now, update the content of main.scala.html to:
@(title: String)(content: Html)
<!DOCTYPE html>
<html>
<head>
<title>@title</title>
</head>
<body>
@content
</body>
</html>

[7]

Getting Started with Play

We can provide the title and content from our Scala code to display this view. A
view can be bound to a specific request through the controllers. So, let's update the
code for our controller SampleAppController, as follows:
package controllers
import play.api.mvc._
import play.api.templates.Html
object SampleAppController extends Controller {
def index = Action {
val content = Html("<div>This is the content for the sample
app<div>")
Ok(views.html.main("Home")(content))
}
}

Downloading the example code

You can download the example code files for all
Packt books you have purchased from your account
at http://www.packtpub.com. If you purchased
this book elsewhere, you can visit http://www.
packtpub.com/support and register to have the
files e-mailed directly to you.
Action and Ok are methods made available by the play.mvc.api package. Chapter 2,
Defining Actions covers them in detail.

On saving the changes and running the application, we will see the page hosted at
http://localhost:9000, as shown in the screenshot:

[8]

Chapter 1

Request handling process

Let's see how the request was handled!
All requests that will be supported by the application must be defined in the conf/
routes file. Each route definition has three parts. The first part is the request method.
It can be any one of GET, POST, PUT, and DELETE. The second part is the path and
the third is the method, which returns a response. When a request is defined in the
conf/routes file, the method to which it is mapped in the conf/routes file is called.
For example, an entry in the routes file would be:
GET
index

controllers.SampleAppController.

This means that for a GET request on the / path, we have mapped the response to be
the one returned from the SampleController.index() method.
A sample request would be:
curl 'http://localhost:9000/'

Go ahead and add a few more pages to the application to get more comfortable,
maybe a FAQ, Contact Us, or About.
The request-response cycle for a Play app, explained in the preceding code is
represented here:

[9]

Getting Started with Play

The public directory is essentially used to serve resources, such as stylesheets,

JavaScript, and images that are independent of Play. To make these files accessible,
the path to public is also added in routes by default:
GET
/assets/*file
public", file)

controllers.Assets.at(path="/

We will see routes in detail in Chapter 3, Building Routes.

The file conf/application.conf is used to set application-level configuration
properties.
The target directory is used by SBT for the files generated during compile, build, or
other processes.

Creating a TaskTracker application

Let us create a simple TaskTracker application, which allows us to add pending tasks
and delete them. We will continue by modifying SampleApp, built in the previous
section. In this app, we will not be using a DB to store the tasks. It is possible to persist
models in Play using Anorm or other modules; this is discussed in more detail in
Chapter 5, Working with Data.
We need a view that has an input box to enter the task. Add another template file,
index.scala.html, to the views, using the template generated in the preceding
section as boilerplate:
@main("Task Tracker") {
<h2>Task Tracker</h2>
<div>
<form>
<input type="text" name="taskName" placeholder="Add a new
Task" required>
<input type="submit" value="Add">
</form>
</div>
}

[ 10 ]

Chapter 1

In order to use a template, we can call its generated method from our Scala code or
refer to it in other templates by using its name. Using a main template can come in
handy when we want to apply a change to all the templates. For example, if we want
to add a style sheet for an application, just adding this in our main template will
ensure that it's added for all the dependent views.
To view this template's content on loading, update the index method to:
package controllers
import play.api.mvc._
object TaskController extends Controller {
def index = Action {
Ok(views.html.index())
}
}

Notice that we have also replaced all occurrences of SampleAppController to

TaskController.
Run the application and view it in the browser; the page will look similar to this figure:

Now, in order to work on the functionality, let's add a model called Task, which
we'll use to represent the task in our app. Since we want to delete the functionality
too, we will need to identify each task using a unique ID, which means that our
model should have two properties: an ID and a name. The Task model will be:
package models
case class Task(id: Int, name: String)
object Task {
private var taskList: List[Task] = List()
def all: List[Task] = {
taskList
[ 11 ]

Getting Started with Play

}
def add(taskName: String) = {
val newId: Int = taskList.last.id + 1
taskList = taskList ++ List(Task(newId, taskName))
}
def delete(taskId: Int) = {
taskList = taskList.filterNot(task => task.id == taskId)
}
}

In this model, we are using a taskList private variable to keep track of the tasks for
the session.
In the add method, whenever a new task is added, we append it to this list. Instead
of keeping another variable to keep count of the IDs, I choose to increment the ID of
the last element in the list.
In the delete method, we simply filter out the task with the given ID and the all
method returns the list for this session.
Now, we need to call these methods in our controller and then bind them to a
request route. Now, update the controller in this way:
import models.Task
import play.api.mvc._
object TaskController extends Controller {
def index = Action {
Redirect(routes.TaskController.tasks)
}
def tasks = Action {
Ok(views.html.index(Task.all))
}
def newTask = Action(parse.urlFormEncoded) {
implicit request =>
Task.add(request.body.get("taskName").get.head)
Redirect(routes.TaskController.index)
}
def deleteTask(id: Int) = Action {
[ 12 ]

Chapter 1
Task.delete(id)
Ok
}
}

In the preceding code, routes refers to the helper that can be used to access the
routes defined for the application in conf/routes. Try running the app now!
It'll throw a compilation error, which says that values tasks is not a member of

controllers.ReverseTaskController. This occurs because we haven't yet

updated the routes.

Adding a new task

Now, let's bind actions to get tasks and add a new task:
GET

controllers.TaskController.index

# Tasks
GET
POST

/tasks
/tasks

controllers.TaskController.tasks
controllers.TaskController.newTask

We'll complete our application's view so that it can facilitate the following:
accept and render a List[Task]
@(tasks: List[Task])
@main("Task Tracker") {
<h2>Task Tracker</h2>
<div>
<form action="@routes.TaskController.newTask()"
method="post">
<input type="text" name="taskName" placeholder="Add a
new Task" required>
<input type="submit" value="Add">
</form>
</div>
<div>
<ul>
@tasks.map { task =>
<li>
@task.name
</li>
[ 13 ]

Getting Started with Play

}
</ul>
</div>
}

We have now added a form in the view, which takes a text input with the taskName
name and submits this data to a TaskController.newTask method.
Notice that we have now added a tasks argument for this template
and are displaying it in the view. Scala elements and predefined
templates are prepended with the @ twirl symbol in the views.

Now, when running the app, we will be able to add tasks as well as view existing
ones, as shown here:

Deleting a task
The only thing remaining in our app is the ability to delete a task. Update the index
template so that each <li> element has a button, whose click results in a delete
request to the server:
<li>
@task.name <button onclick="deleteTask ( @task.id)
;">Remove</button>
</li>

Then, we would need to update the routes file to map the delete action:
DELETE
(id: Int).

/tasks/:id

controllers.TaskController.deleteTask

We also need to define deleteTask in our view. To do this, we can simply add
a script:
<script>
function deleteTask ( id ) {
[ 14 ]

Chapter 1
var req = new XMLHttpRequest ( ) ;
req.open ( "delete", "/tasks/" + id ) ;
req.onload = function ( e ) {
if ( req.status = 200 ) {
document.location.reload ( true ) ;
}
} ;
req.send ( ) ;
}
</script>

Ideally, we shouldn't be defining JavaScript methods in the

window's global namespace. It has been done in this example, so as
to keep it simple and it's not advised for any real-time application.

Now, when we run the app, we can add tasks as well as remove them, as shown here:

I am leaving the task of beautifying the app up to you. Add a style sheet in the public
directory and declare it in the main template. For example, if the taskTracker.css
file is located at public/stylesheets, the link to it in the main.scala.html file
would be:
<link rel="stylesheet" media="screen"
href="@routes.Assets.at("stylesheets/taskTracker.css")">

[ 15 ]

Getting Started with Play

Summary
This chapter gives a basic introduction to the Play Framework. In this chapter,
we have learned how to build simple applications using the Play Framework. We
have gone through its project structure to understand how the framework plugs in
required settings through the build file. We have also discussed the various bits and
pieces of such applications: models, routes, views, controllers, and so on.
In the next chapter, we will cover actions in detail.

[ 16 ]

Get more information Mastering Play Framework for Scala

Where to buy this book

You can buy Mastering Play Framework for Scala from the Packt Publishing website.
Alternatively, you can buy the book from Amazon, BN.com, Computer Manuals and most internet
book retailers.
Click here for ordering and shipping details.

www.PacktPub.com

Stay Connected: