Modules are the way to implement reusability in your application. Code whic does not belong to your core functionality can be combined into a single module and also reused in other applications, or maybe even made open source. Furthermore, there are already quite a lot of modules in Play, and since the release of play 1.1, there is quite a rise of new modules every week. Using other modules is actually pretty easy and requires only one command and one configuration change to get it working.
Basically modules are Play applications themselves, so you are embedding another Play application into your own.
In this example the "search" module is going to be installed. It is a great module which allows you to integrate with Apache Lucene by just adding two annotations to your JPA models. From then on you can do lightning fast queries instead of using your database for full tex search ueries. However, if you want to install any module, you need to have an Internet connection for the first installation. Furthermore, this search module is used as an example in this case; there will be no implementation hits on using it. Please refer to the documentation for this.
Check whether the module is already installed. This should be executed in the directory of a Play application in order to return useful data:
play modules
Check whether the module you want to install is available:
play list-modules
Put this in your conf/dependencies.yml file:
require:
- play
- play -> search headThen run play deps. After you have run and downloaded the module, you will have a ./modules/search-head directory in your application, which gets automatically loaded on application startup.
When starting your application the next time you should see the following startup message:
10:58:48,825 INFO ~ Module search is available (/path/to/app/modules/search-head)
In case you are using an older version of Play than version 1.2, there is another mechanism to install a module, which needs further configuration. Make sure you are inside of the Play application where you want to install the module:
play install search
You are asked whether you are sure you want to install the module, because you need to check whether this module is compatible with the version of Play you are using. The installation tries to install the latest version of the module, but you can choose the module version in case you need an older one.
Follow the hint in the last line and put it into the conf/application.conf file:
module.search=${play.path}/modules/search-headWhen starting your application the next time you should see the following startup message:
10:58:48,825 INFO ~ Module search is available (/home/alex/devel/play/play-1.1/modules/search-head)
From now on you can use the module and its functionality in your code.
The steps are pretty straightforward as it is automated as much as possible. When calling Play install, everything is downloaded as a big package from the Web, unpacked in your Play installation (not your application) and from then on, ready to run in any Play web, once enabled in the configuration. The main difference between the old and new way of adding modules is the fact that the old mechanism stored the modules not in the application but in the framework directory, where as the new mechanism only stores modules inside of the application directory.
Many modules require additional configuration in the conf/application.conf file. For example, if you install a module which persists your models in a MongoDB database, you will need to configure the database connection additionally. However, such cases are always documented, so just check the module documentation in case.
Also if modules do not work, first check whether they work in your version of Play. If this is the case, you should also file a bug report or inform the module maintainer. Many modules are not maintained by the core developers of Play, but instead by users of the Play framework.
As soon as you have added a new module and it includes documentation (most modules do), it will always be available in development mode under http://localhost:9000/@documentation.
There is currently no functionality to update your modules automatically. This is something you have to do manually. In order to keep it up-to-date you can either read the mailing list or alternatively just check the source repository of the module. This should always be listed in the module description page.
Go to http://www.playframework.org/modules/search-head/home for more information about this module.
If you are interested in modules, check out the Chapter 5, Introduction to Writing Modules in this book. It also includes a recipe Using Solr for indexing, which takes up the search topic again.