Bootstrapping a Play application

While it is totally possible to start a Play project from nothing, you might find it more convenient to start from an empty application skeleton and set up the build system to depend on Play so that you can directly focus on the code of your application.

Typesafe Activator (https://typesafe.com/activator) can be used to generate such an empty application skeleton. This tool lists several application templates designed to be used as the project's starting point. Actually, Activator does a bit more than this: it can also compile and run your project and even provide a minimalist development environment with a code editor right in your web browser!

Let's start with a basic Scala or Java application. Download and install Activator by referring to its documentation. Though some templates already support advanced features out of the box, we will begin with a completely empty application and will progressively enhance it with new features (for example, persistence or client-side technologies).

In a *nix terminal, create a new application skeleton by running the following activator command:

$ activator new

You will be asked which application template to use; choose just-play-scala (or just-play-java to create a Java application). Give the application the name shop.

A new directory, shop/, has been created that contains the application's code. Go to this directory and execute the activator run command:

$ cd shop
$ activator run

Activator starts a development HTTP server listening (by default) on port 9000. In your browser, go to http://localhost:9000 to test it; the HTTP server compiles your application, starts it, and processes your HTTP request. If everything works fine, your browser should show a page titled Just Play Scala (or Just Play Java).

You can stop the running application with Ctrl + D.

You can also start Activator without passing it a command name:

$ activator

In such a case, you enter in the project sbt shell, where you can manage the life cycle of your project as in any sbt project. For instance, you can try these commands: clean, compile, run, and console. The last one starts a REPL where you can evaluate expressions using your application's code.

Note

sbt is a build tool for Scala projects. Check out http://www.scala-sbt.org for more details.

Play applications' layout

To explain why you get this result in your browser when you ran the application, let's have a look at the files created by the activator new command. Under the project root directory (the shop/ directory), the build.sbt file describes your project to the build system.

It currently contains a few lines, which are as follows:

name := """shop"""

version := "1.0-SNAPSHOT"

lazy val root = project.in(file(".")).enablePlugins(PlayScala)

The first two lines set the project name and version, and the last line imports the default settings of Play projects (in the case of a Java project, this line contains PlayJava instead of PlayScala). These default settings are defined by the Play sbt plugin imported from the project/plugins.sbt file. As the development of a Play application involves several file generation tasks (templates, routes, assets and so on), the sbt plugin helps you to manage them and brings you a highly productive development environment by automatically recompiling your sources when they have changed and you hit the reload button of your web browser.

Though based on sbt, Play projects do not follow the standard sbt projects layout: source files are under the app/ directory, test files under the test/ directory, and resource files (for example, configuration files) are under the conf/ directory. For instance, the definitions of the Shop and Item types should go into the app/ directory, under a models package.

After running your Play application, try changing the source code of the application (under the app/ directory) and hit the reload button in your browser. The development HTTP server automatically recompiles and restarts your application. If your modification does not compile, you will see an error page in your browser that shows the line causing the error.

Let's have a deeper look at the files of this minimal Play application.

The app/ directory, as mentioned before, contains the application's source code. For now, it contains a controllers package with just one controller named Application. It also contains a views/ directory that contains HTML templates. We will see how to use them in Chapter 3, Turning a Web Service into a Web Application.

The conf/ directory contains two files. The conf/application.conf file contains the application configuration information as key-value pairs. It uses the Human Optimized Configuration Object Notation syntax (HOCON; it is a JSON superset, check out https://github.com/typesafehub/config/blob/master/HOCON.md for more information). You can define as many configuration points as you want in this file, but several keys are already defined by the framework to set properties, such as the language supported by the application, the URL to use to connect to a database, or to tweak the thread pools used by the application.

The conf/routes file defines the mapping between the HTTP endpoints of the application (URLs) and their corresponding actions. The syntax of this file is explained in the next section.