Kick-start to a Play Framework

Hello everyone, welcome to my blog 🙂

In this blog we’ll get familiar with some basic concepts of play framework.

Play is a full-stack framework with all of the components you need to build a Web Application or a REST service, including: an integrated HTTP server, form handling, Cross-Site Request Forgery (CSRF) protection, a powerful routing mechanism, I18n support, and many more.

Why Play?

• Its Model-View-Controller (MVC) architecture is familiar and easy to learn.
• Direct support of common web development tasks and hot reloading saves precious development time.
• It embraces a fully reactive programming model through the use of futures for asynchronous programming, work stealing for maximizing available threads, and Akka for distribution of work.
• Play provides an enhanced development experience (support for routes, templates compilation and auto-reloading) when using the sbt or Gradle build tools.

Let’s dig deeper into play by creating a new project using the following command:

sbt new playframework/play-scala-seed.g8

Directory Structure

Open your project using a basic code editor or import your project in IntelliJ or Eclipse by using ScalaIDE.

After the first successful compilation, the project structure looks like this:

app                      → Application sources
 └ assets                → Compiled asset sources
    └ stylesheets        → Typically LESS CSS sources
    └ javascripts        → Typically CoffeeScript sources
 └ controllers           → Application controllers
 └ models                → Application business layer
 └ views                 → Templates
build.sbt                → Application build script
conf                     → Configurations files and other non-compiled resources (on classpath)
 └ application.conf      → Main configuration file
 └ routes                → Routes definition
dist                     → Arbitrary files to be included in your projects distribution
public                   → Public assets
 └ stylesheets           → CSS files
 └ javascripts           → Javascript files
 └ images                → Image files
project                  → sbt configuration files
 └ build.properties      → Marker for sbt project
 └ plugins.sbt           → sbt plugins including the declaration for Play itself
lib                      → Unmanaged libraries dependencies
logs                     → Logs folder
 └ application.log       → Default log file
target                   → Generated stuff
 └ resolution-cache      → Info about dependencies
 └ scala-2.11
    └ api                → Generated API docs
    └ classes            → Compiled class files
    └ routes             → Sources generated from routes
    └ twirl              → Sources generated from templates
 └ universal             → Application packaging
 └ web                   → Compiled web assets
test                     → source folder for unit or functional tests

This is the standard layout of the play application.

The app/ directory

App directory contains three packages for each component of MVC:

• models
• views
• controllers

You can add your own packages, for example, an app/utils package.

The conf/ directory

The conf directory contains the application’s configuration files. There are two main configuration files:

• application.conf, the main configuration file for the application, which contains configuration parameters
• routes, the routes definition file.

The public/ directory

Public directories are static assets that are split into 3 categories :

• images
• CSS stylesheets
• JavaScript files

There are served directly by the Web server.

The build.sbt file

You’ll find your project’s main build declarations in build.sbt at the root of the project.

The project/ directory

The project directory contains the sbt build definitions:

• plugins.sbt defines sbt plugins used by this project.
• build.properties contains the sbt version to use to build your app.

Now let’s run our project and see how our play application works.
Execute the following command in command in command prompt:

sbt run

Now when you enter http://localhost:9000/ in your browser:

• The browser requests the root / URI from the HTTP server using the GET method.
• The Play internal HTTP Server receives the request.
• Play resolves the request using the routes file, which maps URIs to controller action methods.
• The action method renders the index page, using Twirl templates.
• The HTTP server returns the response as an HTML page.

When you look at the implementation you’ll notice that:

• The routes file maps the request to the controller method.
• The controller action method defines how to handle a request to the root URI.
• The Twirl template are called by the action methods to render the HTML markup.

To view the route that maps the browser request to the controller method, open the conf/routes file. A route consists of an HTTP method, a path, and an action. This control over the URL schema makes it easy to design clean, human-readable, bookmarkable URLs. The following line maps a GET request for the root URL / to the index action in Application:

# Routes
GET         /                        controllers.Application.index

The controller class includes the index action method, as shown below. This is a very simple action method that generate an HTML page from the index.scala.html Twirl template file.

def index = Action {
  Ok(views.html.index())
}

Open app/views/index.scala.html with your text editor. The main directive in this file calls the main template main.scala.html with the string Welcome to generate the page. You can open app/views/main.scala.html to see how a String parameter sets the page title.

So these are some of the basics to kick start with the play framework.
Hope this blog made your learning easier… Happy learning 🙂

In this blog we learnt about play as a web framework, the benefits of developing web application using play web framework, the standard layout of play project and how a play application handles the HTTP requests.

In my next blog we’ll learn more by creating a simple play application.