Developing modules for Liferay Portal requires:
Creating a folder structure: A good folder structure facilitates evolving and maintaining code, especially in collaboration. Popular tools use pre-defined folder structures you’re familiar with.
Writing code and configuration files: A manifest, Java classes, and resources. Modules stubbed out with them let you focus on implementing logic.
Compilation: Configuring dependencies and building the module. Common build tools that manage dependencies include Gradle, Maven, and Ant/Ivy.
Deployment: Interacting with the runtime environment to install, monitor, and modify modules.
There are several good build tools for developing modules. This tutorial demonstrates starting a new module using Liferay Workspace. It’s Liferay’s opinionated build environment based on Gradle and bnd that simplifies module development and automates much of it.
Here are the steps for starting module development:
On completing this tutorial you’ll have created a module and deployed it to a local Liferay Portal bundle.
Setting up a Liferay Workspace
Creating and configuring a Liferay Workspace (Workspace) is straightforward using a tool called Blade CLI (Blade). Blade is a command line tool that creates Workspaces and projects and performs common tasks.
Install Blade if you don’t already have it.
blade executable is now in the system path.
You can create a Workspace in the current directory by executing this command:
blade init [workspaceName]
You’ve created a Workspace! Its folder structure looks like the one shown in the figure below.
Workspace can be configured to use a Liferay Portal installation bundle anywhere on the local file system. The
liferay.workspace.home.dir property in
gradle.properties sets the default bundle location to a folder
[workspace]/bundles (not yet created). For convenience it’s suggested to install a bundle there. If you install it to a different location, uncomment the
liferay.workspace.home.dir property and set it to that location.
The Workspace is ready for creating modules.
Creating a Module
Blade provides project templates and sample projects. The templates stub out files for different types of modules. The samples can be generated in a Workspace and demonstrate many module types. Templates and samples help you create modules fast.
Using Module Templates
The Blade command
blade create -l lists the project templates.
Here’s the command syntax for creating a module:
blade create [options] moduleName
Module templates and their options are described here.
Here’s an example of creating a Liferay MVC Portlet module:
blade create -t mvc-portlet -p com.liferay.docs.mymodule -c MyMvcPortlet my-module
Module projects are created in the
modules folder by default.
Here’s the module project anatomy:
src/main/java/→ Java package root
src/main/resources/content/(optional) → Language properties root
src/main/resources/META-INF/resources/(optional) → Root for UI templates, such as JSPs
bnd.bnd→ Specifies essential OSGi module manifest headers
build.gradle→ Configures dependencies and more using Gradle
The figure below shows an MVC portlet project.
Sample modules are another helpful development resource.
Using Sample Modules
An alternative to creating a module from a template is to generate a sample module. Examine them or modify them for your purposes.
This command lists the sample names:
The figure below shows the listing.
Here’s the Blade samples command syntax:
blade samples [sampleName]
It creates the sample project in a subfolder.
Building a module and deploying it to Liferay is easy.
Building and Deploying a Module
Liferay Workspace provides Gradle tasks for building and deploying modules. Blade’s
blade gw command lets you invoke the Gradle wrapper from any project folder. You can use
blade gw just as you would invoke
gradlew, without having to specify the wrapper path.
In a module folder, execute this command to list the Gradle tasks available:
blade gw tasks
Workspace uses bnd to generate the module’s OSGi
MANIFEST.MF file and package it in the module JAR. To compile the module and generate the module JAR, execute the
jar Gradle task:
blade gw jar
The generated JAR is in the module project’s
build/libs folder and ready for deployment.
Start your Liferay Portal server, if you haven’t already started it.
Blade deploys modules to the local Liferay server. It communicates with the OSGi framework using Felix Gogo shell and deploys modules directly to the OSGi container using Felix File Install commands. The command above uses the default port
To deploy the module, execute this command:
It deploys modules in the current folder tree. For example, executing
blade deploy in the
[workspace]/modules folder deploys all the modules in that folder and its subfolders.
Liferay Dev Studio CE lets you deploy modules by dragging them from the Package Explorer onto the Liferay server. Dev Studio CE provides access to Liferay Workspace Gradle tasks too.
Once you’ve deployed a portlet module, it’s available in the Liferay UI under the application category and name you specified via the portlet component’s
Redeploying Module Changes Automatically
Blade lets you set a watch on changes to a module project’s output files. If they’re modified, Blade redeploys the module automatically. To set a watch on a module at deployment, execute this command in the module project:
blade deploy -w
Here’s output from deploying (and watching) a module named com.liferay.docs.mymodule:
E:\workspaces\my-liferay-workspace\modules\my-module-project>blade deploy -w :modules:my-module-project:compileJava UP-TO-DATE :modules:my-module-project:buildCSS UP-TO-DATE :modules:my-module-project:processResources UP-TO-DATE :modules:my-module-project:transpileJS SKIPPED :modules:my-module-project:configJSModules SKIPPED :modules:my-module-project:classes UP-TO-DATE :modules:my-module-project:jar UP-TO-DATE :modules:my-module-project:assemble UP-TO-DATE :modules:my-module-project:build BUILD SUCCESSFUL Total time: 2.962 secs install file:/E:/workspaces/my-liferay-workspace/modules/my-module-project/build/libs/com.liferay.docs.mymodule-1.0.0.jar Bundle ID: 505 start 505 Scanning E:\workspaces\my-liferay-workspace\modules\my-module-project ... Waiting for changes to input files of tasks... (ctrl-d then enter to exit)
The command output indicates that the module is installed and started, reports the module’s OSGi bundle ID, and stands ready to deploy changes to the module.
Congratulations on a great start to developing your module!