Getting started with Play Framework

It's time for me to test the Play Framework and I'll try to make some posts during my tests about this web framework.

Play Framework is a framework to create web applications in Java. The main goals of this framework are (according to the official site) :

• Hot reload : You can edit your java files and html files and you just have to refresh the browser to see the results
• Stateless model : Play is ready for REST, it can be scaled running multiple instances of the same applications on several servers
• Efficient Template System : The template system is really easy to use, based on Groovy.
• Resolve errors quickly : When an error occurs, Play displays directly the code source in the browser and the location of the error
• Integration : Play provide integration for Hibernate, OpenID, MemCached and others popular frameworks
• Pure Java : You make only Java and HTML, no other things to learn and easy integration in IDE.
• Fast : The startup of application is really fast the rendering of the pages also very fast.

In this post, we'll see how to install the Play Framework and how to write our first Hello World.

Install Play Framework

Before installing Play Framework, you need Java 5.0 or later. Then, you can download a release of Play : http://download.playframework.org/releases/. The latest when I wrote this post is the 1.0.3 version. So let's download this version. After that, just unzip the given archive where you want to install the framework. After that, you just have to add the play command to the path.

In Ubuntu 10.04, I had to do the following :

PLAY_HOME=/usr/share/apps/play/

PATH=$PATH:$PLAY_HOME

chmod +x PLAY_HOME/play

Depending on your configuration, you perhaps have to use sudo for the chmod command. For other systems (Windows and Mac), you also have to add play (play.bat for Windows) to path using the system configuration.

And normally, after that, you can execute the play command :

wichtounet@Linux-Desktop:~$ play

~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   

~ play! 1.0.3, http://www.playframework.org

~ Usage: play cmd [app_path] [--options]

~ with,  new      Create a new application
~        run      Run the application in the current shell
~        help     Show play help

wichtounet@Linux-Desktop:~$ 

Creating a new application

To create a new application, you just have to use the command

play new app_name

You must be in a folder where a folder with the name app_name can be created. For example, let's create a new application "hello" :

wichtounet@Linux-Desktop:~/dev/play$ play new hello

~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.0.3, http://www.playframework.org

~ The new application will be created in /home/wichtounet/dev/play/hello

~ What is the application name? Hello World

~ OK, the application is created.
~ Start it with : play run hello
~ Have fun!

wichtounet@Linux-Desktop:~/dev/play$ 

During the creation, Play will ask you for the name of the application. Here I put "Hello World" as the name of the application. If you go into the new created application folder, you will see the given folders :

• app : The applications itself, Java classes and HTML files
• conf : The configuration of the application
• lib : Contains the Java libraries that the application needs
• public : Contains the public files, images, CSS, JS
• test : Contains the tests (JUnit or Selenium) file

You can launch your application, with the command :

wichtounet@Linux-Desktop:~/dev/play$ play run hello

~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.0.3, http://www.playframework.org

~ Ctrl+C to stop

Listening for transport dt_socket at address: 8000
17:49:56,395 INFO  ~ Starting /home/wichtounet/dev/play/hello
17:49:56,889 WARN  ~ You're running Play! in DEV mode
17:49:56,958 INFO  ~ Listening for HTTP on port 9000 (Waiting a first request to start) ...
17:50:01,670 INFO  ~ Application 'Hello World' is now started !

And you can browse your application at the URL http://localhost:9000/. You will normally see a sample page :

How does it works ?

So now, let's study why this work. If you open the file conf/routes, you will see that line :

GET     /                                       Application.index

That indicates that the index of the project will be serviced from the index method of the Application class. And if you open the app/controllers/Application.java file, you will see :

package controllers;

import play.mvc.*;

public class Application extends Controller {
    public static void index() {
        render();
    }
}

So at this time, the index() only renders the default template. This template is app/views/Application/index.html (like the name of the method and the class) :

#{extends 'main.html' /}
#{set title:'Home' /}
#{welcome /}

We can see that this template extends the main.html template. It sets the title to home and display the welcome prompt. These tags are tags from the Play Framework. Lets change this template to :

#{extends 'main.html' /}
#{set title:'Hello World' /}
<h3>Hello the world !</h3>

And refresh the application page. You will see now only the message "Hello the world". If you want to see something when the controllers is called, just add a System.out.println in the Application.index :

public static void index() {
    System.out.println("render()");
    render();
}

And you will see logs in the console when you refresh the pages :

17:50:01,670 INFO  ~ Application 'Hello World' is now started !
render()
render()
render()
render()
render()

Add a simple new page

To do a little more in this post, let's add a new page : http://localhost:9000/bye. Let's start adding a new route in conf/routes :

GET     /bye                                     Application.bye

So we have to add a method bye in the Application class :

package controllers;

import play.mvc.*;

public class Application extends Controller {
    public static void index() {
        render();
    }

    public static void bye() {
        render();
    }
}

And then, we just need to add a new template bye.html in app/views/Application/ folder :

#{extends 'main.html' /}
#{set title:'Bye' /}
<h3>Bye bye !</h3>

And now, if you go to http://localhost:9000/bye you will see our new page :

Conclusion

Here we are ! With this framework, it's extremely easy to create web applications. And we've only see a very small part of the facilities this framework offers to create web applications. I'll try to write others posts on the subject.

Related articles