Using Play modules

A Play application can be assembled from several application modules. This allows you to reuse application components across several application or split a large application into several smaller applications.

What is a module?

A module is just another Play application; however some differences exist in the way resources are loaded for an application module:

• A module does not have a conf/application.conf file.
• A module can have a conf/routes file, but these routes will not be loaded automatically.
• All files are first searched for in the main application path, then in all loaded modules.
• A module can contain plain Java code packaged as a JAR file in the module/lib directory.
• Everything in a module is optional.

You can create a module with the play new-module command.

How to load a module from an application

The default modules installation path is in the $PLAY_HOME/modules directory. This way all modules are automatically available to all applications run with the framework.

If you want to load external modules from an application, just declare external modules in the application.conf file in the main application.

# Additional modules
# ~~~~~
# A module is another Play application. Add a line for each module you want
# to add to your application. Module paths are either absolute or relative to
# the application root.
#
module.crud=${play.path}/modules/crud

You can also create a standalone project that contains all modules needed by your application. You just need to copy all modules into the same directory as your application.

Let’s say you have a large application with a CMS component, a forum component, a directory component and using the GWT module. You can create a project using this layout:

/my-project
    /cms
    /forum
    /directory
    /gwt
    /main

Here main is the directory of your main application (created using the play new command), gwt is a module installed from the modules repository, and cms, forum and directory are modules created using the play new-module command.

Now from the main application configuration file (my-project/main/conf/application.conf), you can load these modules using:

# Additional modules
# ~~~~~
mdoule.gwt=../gwt
module.cms=../cms
module.forum=../forum
module.directory=../directory

When you run the main application (using play run my-project/main) it will load all these modules in memory as a larger application.

If module paths are relative, they are resolved from the main application root.

Load default routes from modules

A module can provide a default routes file. You can load it in the main application routes file, using a special route declaration:

# Import the default CRUD routes
GET     /admin	     module:crud

You can even load routes from all available modules:

GET     /	     module:*

Using the module repository

The module repository identifies all modules contributed by the community. A module can have several versions. You have to check the module’s documentation for which version you need to use for your framework version.

You can also browse the module repository using the play list-modules command.

gbo-mac:~ guillaume$ play11 list-modules
~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.1-unstable-r761, http://www.playframework.org
~
~ You can also browse this list online at http://www.playframework.org/modules
~
~ [bespin]
~   Bespin online editor
~   http://www.playframework.org/modules/bespin
~   Versions: 1.0, 1.0.1
~
~ [cobertura]
~   Cobertura
~   http://www.playframework.org/modules/cobertura
~   Versions: 1.0
...

You can install a module using the play install {module}-{version} command. For example, to install the Scala support to the framework, use:

play install scala-head

By convention the head version is the unstable version of the module. You can also install the default version of a module by omitting the version information. For example:

play install scala

Modules installed this way are downloaded to the /modules directory of your framework installation. You can change the installation path using the --path option:

play install gwt --path=my-project

Contributing a new module to the module repository

First you need to have an OpenID. It will help us to authenticate you as author of your modules. Then send us a module registration request on the Google Group.

Please tell us:

• More about your module. What is it?
• Your module name. It must match the [a-zA-Z]+ regular expression.
• A short description of the module.
• Your project home page.
• Your OpenID.
• Your module must be hosted somewhere with the source code available and a way to report bugs. If you don’t have any idea, github, Google Code and Launchpad are good choices.

To release your module, simply use the play build-module command. Then connect to the module repository and upload the generated package.

You can of course use the offical Google Group to provide help and share information about your work.