Play modules

A Play application can be assembled from several application modules. This allows you to reuse application components across several applications 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.
• A module can include a documentation page.
• 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

Modules are automatically loaded from the /modules directory of the application. You can use the dependency management system to automatically manage your application modules.

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:*

Add documentation to a module

You can add a documentation page to a module simply by adding a the file documentation/manual/home.textile to the module. Use the same Textile syntax as the Play documentation itself, in ${play.path}/documentation/manual/.

If you are running a Play application that uses one or more modules with documentation, then the local Play documentation at http://localhost:9000/@documentation will include links to their documentation pages under Installed Modules in the side bar.

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$ play list-modules
~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.2, 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 locally using the play install {module}-{version} command. Installing a module locally allows you to use it from several application without having to install a different copy in each application. It is useful for large modules that are more like framework extensions than extensions to your application.

For example, to install Scala support in 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.

Continuing the discussion

Learn how efficiently manage your modules using Dependency management.