Archive for February, 2011

Play Modules

Posted: February 27, 2011 in Play Framework

I have been asked a few times since writing the Play Framework book about how modules fit into the Play Framework. I didn’t think it made sense to add modules into the first edition, as it was intended as an introduction, so I thought I would add a blog here instead.

Before we being, let first understand what we mean by a play module.

What is a module
A module in play is actually little more than an organisation of your code base. The structure of a play module is very much the same as a standard play application. You will see an app directory (with the normal controllers, views and models), you will see also a conf directory (without an application.conf) and finally a src folder. There is no application.conf as a module will conform to the configuration set out by the application that includes this module.

Note that when your module is running inside an application it has access to all of the applications properties, as if your module was directly inside the application itself.

Why use modules
The idea behind using modules is re-usability and separation. Imagine a scenario where you are building a web application that consists of several discrete pieces of functionality, such as an online Office suite, you may create a set of modules as follows:

  • Core Application
  • Authentication
  • Word processing
  • Presentations
  • Spreadsheets
  • etc

The core application would be your main application that tied all the modules together, and the authentication, word processing, presentations and spreadsheets would each be an individual module.

You could even distribute these modules to different teams to work on.

But I am not going to write an Office clone!
Okay, but the theory transfer to much smaller modules. You modules really could be any discrete piece of functionality, such as admin functions, authentication, dashboards. Anything! Its all about clean separation of concerns and re-usability. Your authentication module could be lifted to your next application with no more effort than simply dropping the directory structure and adding a line in your application.conf.

Creating a Module
Lets take the idea of having a project that has some authentication requirements that we want to split into a new module.

First we will create our main application.

play new core-app

Next we will create our module

play new-module auth

To include our module into our core application, we simply update the application.conf and add a module in the same way we would add a community module.


So, the path is module.=

And that is it, your module will be available. But there is nothing in it yet.

What do I put in my Module
Well this is really up to you. For the purposes of our module, the most obvious things to add to our module would be a User model class, an Authenticate controller containing methods for registration, login, and checking authority, and finally views to go with the registration and login actions.

We won’t go into how to build these, because you can quite simply use the Secure module already available in Play for most of this stuff. It simply serves as a nice example of how to separate out some clearly de-marked functionality.

What can’t I do in a module?
Not a lot really. Remember, a module is very much a play application, but just does not have an application.conf, so can’t be run directly. As soon as it is attached to a play application, it can do anything a play application can do, without exception.

What about the PlayPlugin and src folders?
Right at the beginning we mentioned a src folder. In that folder there is also a play.plugins file.

Firstly, the /src directory is compiled when the module is built using the build-module command. The idea, of this directory is for utility classes that don’t have anything to do with Play. .

When the module is built, the contents of the src folder is compiled into a jar file ready for distribution.

Play Plugins are another entirely different topic, which are designed to modify how the Play Framework functions. A great example of this is the DocViewerPlugin which comes bundled into Play. The module simple adds a number of routes to your routes file (if in DEV mode), that allows you to see the core play framework documentation by using the URL /@documentation. The play.plugins file specifies the order of invocation of the play plugins.

My new module is amazing, how do I share it?
Use the build-module command to build a distribution of your module. Announce your module on Google Groups and Guillaume or one of the Play team will give you access to the module repository. You will need to provide an OpenID as well. Once you have access, you can specify the description of your module, and share your module via GitHub or another repository.

You should also add some documentation about your project to /documentation/manual/home.textile.


The eBook – “Introducing the Play Framework” will shortly be coming out of beta. The good news is that there have been no changes to the content as a result of the beta phase, so for all who bought the beta, your faith was well placed!

Also, I would like to thank everyone for the very encouraging feedback. If anyone would like to add a comment to be published in the final release, just drop me an email.

Once the book comes out of beta, it will probably go up by a few pounds, so if anyone wants to save a little, get in quick!