Starting Module Development

Developing modules for Liferay DXP requires:

• Creating a folder structure: A good folder structure facilitates evolving and maintaining code, especially in collaboration. Popular tools use pre-defined folder structures familiar to developers.

• Writing code and configuration files: A manifest, Java classes, and resources. Modules stubbed out with them let developers focus on implementing logic.

• Compilation: Acquiring 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 on Liferay DXP. This tutorial demonstrates starting a new module using Liferay Workspace. It’s Liferay’s opinionated build environment based on Gradle and BndTools that simplifies module development and automates much of it.

Note: Liferay supports developers using their build tool of choice. In addition to providing Liferay Workspace for those who don’t already have a preferred build environment, Liferay provides good support for Maven and Gradle. The following tutorials and samples demonstrate developing in these environments.

• Maven tutorials and samples

• Gradle in Liferay Developer Studio and samples

Note: Themes and Layout Templates are not built as modules. To learn how to create them, see the Themes and Layout Templates tutorials.

Here are the steps for starting module development:

1. Set up a Liferay Workspace

2. Create a module

3. Build and deploy the module

On completing this tutorial you’ll have created a module and deployed it to a local Liferay DXP 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 performs common tasks.

Follow the steps in this tutorial to install Blade if you don’t already have it.

The 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 directory structure looks like the one shown in the figure below.

Figure 1: Liferay Workspace aggregates projects so they can leverage the Gradle build environment.

Workspace can be configured to use a Liferay DXP 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 Liferay DXP bundle there. If you install it to a different location, uncomment the liferay.workspace.home.dir property and set it to that location.

Note: User interfaces in Liferay Developer Studio lets developers create and import Liferay Workspace projects.

To create a project, follow the tutorial Creating a Liferay Workspace Project with Liferay Developer Studio.

To import a project, use the wizard from File → Import → Liferay → Liferay Workspace Project.

The Workspace is ready for creating modules.

Creating a Module

Blade provides module templates and module samples. The templates stub out files for different types of modules. The samples can be generated in a Workspace and demonstrate many module types. Developers can use templates and samples to develop modules.

Using Module Templates

The Blade command blade create -l lists the module templates.

Figure 2: Blade's `create` command generates a module based on a template. Executing `create -l` lists the template names.

Note: Liferay Developer Studio’s module wizard lets developers select a template for their module project. For details, see the tutorial Creating a Module with Liferay Developer Studio.

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 resource bundle 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 module project.

Figure 3: Liferay modules use the standard Maven directory structure.

Sample modules are another helpful development resource.

Using Module Samples

An alternative to creating a module from a template is to generate a sample module. Developers can examine or modify sample modules as desired.

This command lists the sample names:

blade samples

The figure below shows the listing.

Figure 4: The `blade samples` command lists the names of sample modules developers can create, examine, and modify to meet their needs.

Here’s the Blade samples command syntax:

blade samples <sampleName>

It creates the sample project in a subfolder of the current folder.

Building a module and deploying it to Liferay DXP is easy.

Building and Deploying a Module

Liferay Workspace provides Gradle tasks for building and deploying modules. Blade’s blade gw command solves a common need in Gradle projects: invoking the Gradle wrapper from any project directory. You can use blade gw just as you would invoke gradlew, without having to specify the wrapper path.

Note: For an even simpler Gradle wrapper command, install gw.

(sudo) jpm install gw@1.0.1

Usage: gw <task>

In a module folder, execute this command to list the Gradle tasks available:

blade gw tasks

Workspace uses BndTools 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 to Liferay DXP.

Start your Liferay DXP server, if you haven’t already started it.

Tip: To open a new terminal window and the Workspace’s Liferay DXP server (bundled with Tomcat or JBoss/Wildfly), execute this command:

blade server start -b

Blade can deploy modules to any local Liferay DXP server. It communicates with Liferay DXP’s OSGi framework using Felix Gogo shell and deploys modules directly to the OSGi container using Felix File Install commands. The command uses the default port 11311.

To deploy the module, execute this command:

blade deploy

Also Blade lets developers deploy all modules in the current folder tree. To deploy all modules in a Workspace’s modules folder, for example, execute blade deploy in the <workspace>/modules folder.

If you’re using Liferay Developer Studio, you can deploy modules by dragging them from the Package Explorer onto the Liferay DXP server. Developer Studio provides access to Liferay Workspace Gradle tasks too.

Figure 5: Liferay Developer Studio lets developers deploy modules using drag-and-drop.

Note: When deploying a module to Liferay DXP using Blade CLI, the module is directly installed into Liferay DXP’s OSGi container. This means that the module is stored differently in Liferay DXP than if it were copied into the LIFERAY_HOME/deploy folder. See the Deploying Modules with Blade CLI tutorial for more information.

Once you’ve deployed a portlet module, it’s available in the Liferay DXP UI under the application category and name you specified via the portlet component’s com.liferay.portlet.display-category and javax.portlet.display-name properties in the @Component annotation.

Figure 6: Here's a bare-bones portlet based on one of Liferay's module templates.

Redeploying Module Changes Automatically

Blade lets developers 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)

Output from the blade deploy -w command indicates that the module is installed and started, reports the module’s OSGi bundle ID, and stands ready to redeploy the module if its output files change.

Congratulations on a great start to developing your module!

Related Articles

Configuring Dependencies

Liferay Workspace

Tooling

OSGi Basics for Liferay Development

Portlets