Documentation

Five cool things you can do with play

Five examples to show the philosophy behind the play framework.

1. Bind an HTTP parameter to a Java method parameter

Retrieving HTTP parameters from Java code is really simple with play. Just declare method parameters with the same name as the HTTP parameters.

For example, with this request:

/articles/archive?date=08/01/08&page=2

You can retrieve the date and page parameters by declaring them as Java method parameters:

public static void archive(Date date, Integer page) {
    List<Article> articles = Articles.fromArchive(date, page);
    render(articles);
}

Play will use the static type of the method parameter, to translate the HTTP value as a Java object.

Smart binding also works with any classes.

public class Person {
    public String name;
    public Integer age;
}

A simplistic controller action to add a person may look like this:

public static void add(Person p) {
    p.save();
}

The HTML form defines fields with composite names:

<form action="/Directory/add" method="POST">
    Name: <input type="text" name="p.name" />
    Age: <input type="text" name="p.age" />
</form>

2. Redirect to an action by calling the corresponding Java method

There is no equivalent to the Java Servlet forward command with play. But redirecting to another action is really simple. Just call the corresponding Java method and play will generate the correct HTTP “Redirect” response.

public static void show(Long id) {
    Article article = Article.findById(id);
    render(article);
}
 
public static void edit(Long id, String title) {
    Article article = Article.findById(id);
    article.title = title;
    article.save();
    show(id);
}

Note how at the end of the edit action, we redirect to the show action.

In any template you can use the equivalent syntax to generate the link:

<a href="@{Article.show(article.id)}">${article.title}</a>

That will generate the following HTML:

<a href="/articles/15">My new article</a>

3. Don’t Repeat Yourself when passing Java objects to templates

In most Java frameworks, in order to pass Java objects to the template system you need to write something like:

Article article = Article.findById(id);
User user = User.getConnected();
Map<String, Object> model = new HashMap<String,Object>();
model.put("article", article);
model.put("user", user);
render(model);

With play, you can just write:

Article article = Article.findById(id);
User user = User.getConnected();
render(article, user);

And retrieve objects from their Java local name in the template. That saves a lot of useless lines of code...

4. JPA on steroids

JPA is surely the best ORM API available for Java. If you know it you will be amazed how simpler it become with play. Nothing to configure, play will automatically start the JPA Entity Manager using Hibernate and magically synchronize it when code is reloaded.

Moreover, if you use the provided play.db.jpa.Model superclass it will help to make your code prettier. Take a look:

public void messages(int page) {
    User connectedUser = User.find("byEmail", connected());
    List<Message> messages = Message.find(
        "user = ? and read = false order by date desc",
        connectedUser
    ).from(page * 10).fetch(10);
    render(connectedUser, messages);
}

5. Straightforward file upload management

File upload management is very simple with play.

The HTML form:

<form action="@{Article.uploadPhoto()}" method="POST" enctype="multipart/form-data">
    <input type="text" name="title" />
    <input type="file" id="photo" name="photo" />
    <input type="submit" value="Send it..." />
</form>

And the Java code:

public static void uploadPhoto(String title, File photo) {
   ...
}

How could it be easier?