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

Prerequisites

To register a new module, the following are required.

1. A Google account, to post on the Google Group.
2. An OpenID for your developer log-in (you can use your Google account for this).
3. A module name that matches [a-zA-Z]+ regular expression.
4. The module must include documentation.
5. A module home page with the source code available and a way to report bugs, e.g. a GitHub, Google Code or Launchpad project.

Module registration

To use your Google account as your OpenID, you need to discover its full URL, as follows.

1. On http://www.playframework.org/modules, under Developer login enter https://www.google.com/accounts/o8/id and click the Login button.
2. Log in to your Google account.
3. Make a note of the full Google OpenID URL under Developer login, e.g. https://www.google.com/accounts/o8/id?id=BItOawk7q69CFhRarQIo

Post a module registration request on the play-framework Google Group. For example:

Subject: Module registration request: {module name}
 
Module name:
jqueryui
 
Display name:
jQuery UI
 
Description:
Working examples of jQuery UI widgets, integrated with a Play application.
 
Project home page:
https://github.com/hilton/jqueryui-module
 
OpenID:
https://www.google.com/accounts/o8/id?id=BItOawk7q69CFhRarQIo

When your module has been registered, you can publish a release.

Releasing your module

To release your module:

1. set the module version number in the first line of conf/dependency.yml, e.g. self: play -> jqueryui 1.0
2. build the module with the play build-module command
3. log in to http://www.playframework.org/modules under Developer login
4. browse to your module’s page, via the link on http://www.playframework.org/modules/developers under Your modules
5. upload the generated ZIP file from your your module’s dist/ directory, using the form under Manage module releases

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.