Documentation

CRUD: Administration generator

The CRUD (Create, Read, Update, Delete) module generates a fully usable web interface for your JPA Model objects.

Let’s see a simple example.

Enable the CRUD module for the application

In the /conf/application.conf file, enable the CRUD module by adding this line:

# The crud module
module.crud=${play.path}/modules/crud

Import default CRUD routes

In the conf/routes file, import the default module routes by adding this line:

# Import CRUD routes
*      /admin              module:crud

Note that using the default routes file is not required. You can also define your own routes, or mix the two.

Create a User class

We will start by creating a User class:

package models;
 
import play.*;
import play.db.jpa.*;
 
import javax.persistence.*;
import java.util.*;
 
@Entity
public class User extends Model {
 	
	public String name;
	public String email;
	public String address;
 	
}

Create the Users controller

Then, we create a simple controller that just inherits the CRUD controller.

package controllers;
 
public class Users extends CRUD {
    
}

Now open http://localhost:9000/admin and you should see the User admin area.

The controller’s class name has to be the model class name with a final ‘s’. If you want to name it differently, you can do it using an annotation.

package controllers;
 
import models.User;
 
@CRUD.For(User.class)
public class AdminUsers extends CRUD {
   
}

The User form

Click the Add button, and you should see the User form.

Now we can add some validation rules to the User class:

package models;
 
import play.*;
import play.db.jpa.*;
 
import javax.persistence.*;
import java.util.*;
 
import play.data.validation.*;
 
@Entity
public class User extends Model {
 	
    @Required
    @MinSize(8)
    public String name;
	
    @Required
    @Email
    public String email;
	
    @Required
    @MaxSize(1000)
    public String address;
 
    public String toString() {
        return email;
    }
	
}

Refresh the User form and you will see that the validation is automatically applied.

Change the form label

Add these lines to the conf/messages file in your application:

name=Name
email=Email address
address=Postal address

And refresh the User form.

Create a User and customize the list view

The default list view uses only one column containing the result of the object’s toString() method.

To customize this view, we need to create the /app/views/Users/list.html template in the application.

Open a shell, go the application directory and type:

play crud:ov --template Users/list

This will copy the default CRUD list.html template to the Users/list.html template in your application, overwriting it if present.

Edit the template like this:

#{extends 'CRUD/layout.html' /}
 
<div id="crudList" class="${type.name}">
	
	<h2 id="crudListTitle">&{'crud.list.title', type.name}</h2>
 
	<div id="crudListSearch">
		#{crud.search /}
	</div>
 
	<div id="crudListTable">
		#{crud.table fields:['email', 'name'] /}
	</div>
	
	<div id="crudListPagination">
		#{crud.pagination /}
	</div>
	
	<p id="crudListAdd">
		<a href="@{blank()}">&{'crud.add', type.modelName}</a>
	</p>
</div>

and refresh the list.

Custom fields rendering: the crud.custom tag

You can go a bit further by customizing the way each field of your '‘User’' entity is displayed in the list and form views.

To customize a field, use the '‘#{crud.custom}’' tag:

#{crud.table fields:['name', 'company']}
 
   #{crud.custom 'company'}
       <a href="@{Companies.show(object.company.id)}">${object.company.name}</a>
   #{/crud.custom}
 
#{/crud.table}

You can also display additional columns or form inputs by defining custom handlers:

#{crud.table fields:['name', 'company', 'edit']}
 
   #{crud.custom 'company'}
       <a href="@{Companies.show(object.company.id)}">${object.company.name}</a>
   #{/crud.custom}
 
   #{crud.custom 'edit'}
       <a href="@{Users.edit(object.id)}">Edit</a>
   #{/crud.custom}
 
#{/crud.table}

List of String and List of enumeration

The CRUD module is showing them as a text field. In this text field, the list is represented by a comma separated list of String. For example:

@Entity
public class Account extends Model {
 
        @CollectionOfElements
        public Set<ContentType> contentTypes;
 
        @CollectionOfElements
        public Set<String> usernames;
 
        public Account(Set<String> usernames {
                super();
                this.usernames = usernames;
        }
}

This is shown as: “myEnumId1”,“myEnumId2” for the contentTypes and “string1”,“string2” for the user names. Per definition, this is what you should first customize in your CRUD module.

Limitation

The CRUD module will show the relationships that are unidirectional in one entity: the one that does not have the mappedBy attribute.