First of all, make sure that you have a working Play installation. You only need Java (version 6 minimum), and to unzip the Play binary package to start; everything is included.

As we will use the command line a lot, it’s better to use a Unix-like OS. If you run a Windows system, it will also work fine; you’ll just have to type a few commands in the command prompt.

You will of course need a text editor. If you are used-to a fully-featured Java IDE, such as Eclipse or IntelliJ, you can of course use it. However, with Play you can have fun working with a simple text editor like TextMate, Emacs or vi. This is because the framework manages compilation and the deployment process itself.

Now that Play is correctly installed, it’s time to create the new application. Creating a Play application is pretty easy and fully managed by the Play command line utility. This encourages a standard project layout across all Play applications.

Open a new command line and enter:

$ play new todolist

The Play tool will ask you a few questions. Choose to create a simple Java application project template.

The play new command creates a new directory todolist/ and populates it with a series of files and directories. The most important are as follows.

app/ contains the application’s core, split between models, controllers and views directories. This is the directory where .java source files live.

conf/ contains all the application’s configuration files, especially the main application.conf file, the routes definition files and the messages files used for internationalization.

project/ contains the build scripts. The build system is based on sbt. But a new play application comes with a default build script that will just works fine for our application.

public/ contains all the publicly available resources, which includes JavaScript, stylesheets and images directories.

test/ contains all the application tests. Tests can be written as JUnit tests.

Because Play uses UTF-8 as the single encoding, it’s very important that all text files hosted in these directories use this encoding. Make sure to configure your text editor accordingly. In the windows system the editor configuration must be ANSI encodeNote: Read more about Anatomy of a Play application .

Here, the action returns a 200 OK response with an HTML response body. The HTML content is provided by a template. Play templates are compiled to standard Java methods, here as views.html.index.render(String message).

This template is defined in the app/views/index.scala.html source file:

The first line defines the function signature. Here it takes a single String parameter. Then the template content mixes HTML (or any text-based language) with Scala statements. The Scala statements start with the special @ character.

Note: Don’t worry about the template engine using Scala as its expression language. This is not a problem for a Java developer, and you can almost use it as if the language was Java. We explain the templating system in a bit more detail below.

Now let’s make some modifications to the new application. In the Application.java change the content of the response:

public static Result index() {
return ok("Hello world");
}

With this change, the index action will now respond with a simple text/plainHello world response. To see this change, just refresh the home page in your browser:

There is no need to compile the code yourself or restart the server to see the modification. It is automatically reloaded when a change is detected. But what happens when you make a mistake in your code? Let’s try:

public static Result index() {
return ok("Hello world);
}

Now reload the home page in your browser:

As you can see, errors are beautifully displayed directly in your browser.

We create a route to list all tasks, and a couple of others to handle task creation and deletion. The route to handle task deletion defines a variable argument id in the URL path. This value is then passed to the deleteTask action method.

Now if your reload in your browser, you will see that Play cannot compile your routes files:

This is because the routes reference non-existent action methods. So let’s add them to the Application.java file:

As you see we use TODO as result in our actions implementation. Because we don’t want to write the actions implementation yet, we can use the built-in TODO result that will return a 501 Not Implemented response.

We have also created a bunch of static methods to manage Task operations. For now we wrote dummy implementation for each operation, but later in this tutorial we will write implementations that will store the tasks into a relational database.

We also imported helper._ that give us the form creation helpers, typically the form function that creates the HTML <form> with filled action and method attributes, and the inputText function that creates the HTML input given a form field.

We use bindFromRequest to create a new form filled with the request data. If there are any errors in the form, we redisplay it (here we use 400 Bad Request instead of 200 OK). If there are no errors, we create the task and then redirect to the tasks list.

It’s now time to persist the tasks in a database to make the application useful. Let’s start by enabling a database in our application.

For now we will use a simple in memory database using H2, follow the process described in the Accessing an SQL database page.

No need to restart the server, refreshing the browser is enough to set up the database.

We will use EBean (Play’s default ORM) in this tutorial to query the database. So you’ll have to enable it as well. Define a default Ebean server following instructions on Using the Ebean ORM page page.

By doing this we create an Ebean server connected to the default datasource, managing all entities found in the models package. Now it’s time to transform our Task class to a valid EBean entity:

We made the Task class extend the play.db.ebean.Model super class to have access to Play built-in Ebean helper. We also added proper persistence annotations, and created a find helper to initiate queries.

Using system properties we override the application configuration when running on Heroku. But since heroku provides a PostgreSQL database we’ll have to add the required driver to our application dependencies.