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.

  1. opensas says:

    well, thanks a lot for a clear and precise explanation

  2. opensas says:

    I’ve just published an article on play framework modules and deploying to openshift.

  3. codemwnci says:

    I read it this morning, a really nice article. It did make me appreciate the simplicity of Heroku because of the native support for Play! OpenShift looks interesting, but Play is so much easier when not requiring the WAR export and deploy method.

    • opensas says:

      Yes indeed, in fact openshift philosophy is the same, you have to provide a pom.xml to build the app on the cloud, unfortunaltely it has no play native support, yet… But openshift has several advatanges, like 500MB of space (sources + db) for free, git repo, mysql + phpmyadmin, mongodb + rockmongo, jenkins support, etc…

      • dileep says:

        This seems good, but how can we skip the module while building..Any idea. My requirement is like this, some of our customer need not all modules, i have to skip some of them

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s