liferay maven plugin – Liferay MVC Portlet with Maven

Liferay supports maven to create various liferay maven plugin like portlets, hook, theme, layout and web plugins.

Till version 6.1, ANT was the only way to build the portlet in Liferay out of the box. Starting with Liferay 6.2, Liferay starts providing support for Maven to build various Liferay maven plugin.

This is also reflected in Liferay Developer Studio (and the eclipse plugin). You can build Liferay maven plugins starting from Liferay Developer Studio 2.x.x. At the time of writing this, the latest version of Liferay IDE is 3.1.2 GA3, which ships with the Neon 3 version of eclipse.

Maven is a very powerful tool that runs through POM (called Project Object Model). It’s a complete project management tool rather than just a build tool like Ant.

There are many advantages of Maven over Ant like

  • Dependency Management
  • More powerful and componentized builds
  • Better debugging
  • Better collaboration
  • Reduce duplication
  • More consistent project structure
  • Modular build management.
  • Providing Javadoc
  • Collaboration

You can refer to http://www.kyleblaney.com/benefits-of-maven-over-ant/ for more details.

In this article, I will be showing how to create Liferay MVC with maven, which is the simplest and most widely used in Portal development. Let’s start it.

Installing and configuring Maven

Before doing anything else, you need to install Maven on your machine.  Download Maven and extract it on your local drive. Let say c:/maven.

Set new environment variable M2_HOME and point it to the home directory of maven. c:/maven in our case.

Edit the PATH environment variable and add %M2_HOME%\bin. This will make mvn command available in the command prompt for any directory.

Maven profile

While working with maven, you can define a set of project-specific attributes, called a Maven Profile (for each individual project). Maven profiles are nothing but project-specific settings which is used by maven.

You need to create a Maven profile for your project. You can get more about maven profile from this link.

Maven profiles are defined in the maven configuration file, which is an XML.( we will see about this in a short while). While creating a maven project/module, you can use one profile at a time.

You can relate the maven profile structure from the following relation.

Liferay Maven Plugin - Maven Profile to Project structure

How to define Maven profile

To define the maven profile, go to the %M2_HOME%/conf directory (c:/maven/conf in our case) and open the settings.xml file. It’s a global configuration file for maven.

You will see the element – <profiles>. Just below it, add the following lines. I had given settings for Liferay 6.2 GA6

<profile>
  <id>custom-maven-profile</id>
   <properties>
        <liferay.maven.plugin.version>6.2.5</liferay.maven.plugin.version>
        <liferay.auto.deploy.dir>E:/techblog/liferay-portal-6.2-ce-ga6/deploy</liferay.auto.deploy.dir>
        <liferay.app.server.deploy.dir>E:/techblog/liferay-portal-6.2-ce-ga6/tomcat-7.0.62/webapps</liferay.app.server.deploy.dir>
        <liferay.app.server.lib.global.dir>E:/techblog/liferay-portal-6.2-ce-ga6/tomcat-7.0.62/lib/ext </liferay.app.server.lib.global.dir>
        <liferay.app.server.portal.dir>E:/techblog/liferay-portal-6.2-ce-ga6/tomcat-7.0.62/webapps/root</liferay.app.server.portal.dir>
        <liferay.version>6.2.5</liferay.version>
    </properties>
</profile>

Id:- shows the name by which the maven profile is uniquely identified. We will use this while creating Liferay plugins from Liferay developer studio (or eclipse).

Properties:- profile-specific properties. If you observe, those are Liferay server-specific path which is used by maven to solve Liferay specific dependencies in your Liferay Maven plugin and the path (deploy) where Maven will copy-paste the generated WAR files.

Activating the Maven profile

A New Maven profile is created. Now you need to make it active so that Maven can use it to build artifacts. To make it active, after completing </profiles> elements, just add the below line.

<activeProfiles>
      <activeProfile>custom-maven-profile</activeProfile>
</activeProfiles>

Special Note:- You can define as many profiles as you want. But you should make only one profile active. If you defined two profiles in <activeProfiles>, you wouldn’t get any error, but then maven will take the last active profile in this sequence as consideration.

So it’s always advisable to make sure you have just one profile defined as an active profile.

Configure Maven profiles in eclipse

The next step is used to select this profile from Liferay Developer Studio (LDS) or eclipse.

Open LDS (or eclipse) click on Windows–>Preferences–>Maven. Expand it and choose User Settings, as shown below.

Liferay maven plugin - configure maven profile in eclipse / Liferay developer studio

In Global Settings, choose the path of settings.xml of maven (c:/maven/confg/settings.xml file in our case)

At this moment, all the maven profiles (which are defined in maven settings.xml) will be available in eclipse.

Congratulation …. the groundwork is done, and we are ready to create the Liferay Maven plugin. To make it simple, we will start with the portlet plugin.

liferay maven plugin - Liferay plugins with Maven

Liferay Maven plugin – Create Liferay MVC Portlet.

Start Liferay Developer Studio (LDS) and click on File –>New –>Liferay Plugin Project, and you will see the below wizard on the screen.

liferay maven plugin - create Liferay MVC Portlet with Maven

Explanation:-

Project Name:-

This is the plugin name. Please note that this wizard will create a plugin with the exact same name that you give here.

Unlike in the previous version of LDS (or eclipse with Liferay plugin), which appends -portlet (plugin type) at the end of the project name.

Display Name:-

As its name, this would be the portlet’s visible name when you place it on the page.

Build type:-

There would be 2 options, 1) Ant and 2) Maven. Choose Maven, and you will see the next set of parameters as below.

Artifact version:-

The artifact is a file that gets deployed on the maven repository. Every artifact has a version. Since your Liferay plugin would also be deployed on the maven repository as a plugin, you need to give an artifact version of your plugin.

This artifact version will be used by other Liferay maven plugins to define a dependency on your plugin. You may browse more about Artifact in Maven.

Just give artifact version as 1.0.0-SNAPSHOT. On releasing a newer version of your plugin in the future, you can update this version. This is similar; for example, Spring has 3.3.2, 4.4.1 versions, etc.

Group Id:-

This will uniquely identify your project across all the plugins/component in the maven repository. This would basically group the name as suggested. While giving group Id, you need to follow certain naming conversion.

Active Profile:-

These are the profiles that we defined in the maven settings XML file in the above step. Select on the rightmost icon (having a small triangle – marked as 1 in the below image), which will open the wizard to select profile as follows.

liferay maven plugin - configure maven profile in eclipse

 

All available profiles are visible on the left side. Click on the one (custom-maven-profile in our case) which you want to set for your plugin at the right end side and click the arrow. Click OK to set profile.

Location:-

Unlike Ant, Maven doesn’t force you to put your Liferay Maven plugin to a specific folder (You need to place your portlet plugin inside plugin-SDK if you choose ANT).

It means you are free to create your portlet plugin anywhere. By default, the location of your plugin portlet is under the eclipse workspace.

If you wish to change, just un-check the ‘Use default location’ checkbox and give the appropriate path. Please make sure the location that you choose is empty, or else it indicates an error like “Project location is not empty or a parent pom.”  There is one exception to this. If you created a parent project, then you can create other plugins under it. In that case, it’s not required to be an empty directory.

I gave a custom path as E:\Nilang\Tech blog\lr-plugin.

Plugin Type:-

It supports various Liferay maven plugin types like Portlet, Service Builder Portlet, Hook, Layout Template, Theme, Ext, and Web. Choose the Portlet (which is by default selected)

Choose Portlet Framework

Keep the rest of the thing as is and click on the Next button. You will see the wizard as follows.

Liferay Maven Plugin - Choose portlet framework

Starting from Liferay Developer Studio 2.x.x, you can create a portlet plugin with various frameworks like Liferay MVC, JSF, Spring MVC, and Vaadin.

Portlet name and Display name are the same (But we can change) that we gave in the previous screen. Choose the Liferay MVC (Default) as a portlet framework and click on Finish.

Liferay Maven Plugin – Project structure

Congratulation, you have successfully created your plugin in maven, and the project structure would be as below.

Liferay Maven Plugin - Project Structure

  • Note that the plugin name is exactly the same that we gave while creating the plugin. It hasn’t append -portlet at the end, just like if we created with Ant.
  • All your Java classes would go under src/main/java.
  • All your resources file ( for example, language properties) resides under src/main/resources.
  • Js and css would go in a respective folder under \webapp.
  • Liferay specific configuration files like portlet.xml, liferay-display.xml, liferay-portlet.xml, liferay-plugin-package.properties would go under WEB-INF.
  • You can write your custom portlet class under /src/main/java with your custom package. You also need to make the appropriate change in portlet.xml located under WEB-INF.

Once you build the plugin with maven, the WAR file would be created under the target folder.

Liferay Maven Plugin – POM Structure

Since this is a maven project, you can find pom.xml at the project folder level. It will look like as below.

<?xml version="1.0"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.opensource.techblog.sample</groupId>
    <artifactId>sample-mvc</artifactId>
    <packaging>war</packaging>
    <name>sample-mvc Portlet</name>
    <version>1.0.0-SNAPSHOT</version>
    <build>
        <plugins>
            <plugin>
                <groupId>com.liferay.maven.plugins</groupId>
                <artifactId>liferay-maven-plugin</artifactId>
                <version>${liferay.maven.plugin.version}</version>
                <executions>
                    <execution>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>build-css</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <autoDeployDir>${liferay.auto.deploy.dir}</autoDeployDir>
                    <appServerDeployDir>${liferay.app.server.deploy.dir}</appServerDeployDir>
                    <appServerLibGlobalDir>${liferay.app.server.lib.global.dir}</appServerLibGlobalDir>
                    <appServerPortalDir>${liferay.app.server.portal.dir}</appServerPortalDir>
                    <liferayVersion>${liferay.version}</liferayVersion>
                    <pluginType>portlet</pluginType>
                </configuration>
            </plugin>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.5</version>
                <configuration>
                    <encoding>UTF-8</encoding>
                    <source>1.6</source>
                    <target>1.6</target>
                </configuration>
            </plugin>
            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>2.5</version>
                <configuration>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
        </plugins>
    </build>
    <dependencies>
        <dependency>
            <groupId>com.liferay.portal</groupId>
            <artifactId>portal-service</artifactId>
            <version>${liferay.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.liferay.portal</groupId>
            <artifactId>util-bridges</artifactId>
            <version>${liferay.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.liferay.portal</groupId>
            <artifactId>util-taglib</artifactId>
            <version>${liferay.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.liferay.portal</groupId>
            <artifactId>util-java</artifactId>
            <version>${liferay.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>javax.portlet</groupId>
            <artifactId>portlet-api</artifactId>
            <version>2.0</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <version>2.4</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>javax.servlet.jsp</groupId>
            <artifactId>jsp-api</artifactId>
            <version>2.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

Quick observation:-

The first few initial lines mentioned the groupId, artifactId, version, and name. The packaging is war means maven will generate a WAR file after building the plugin.

Just comment out following line below build–>plugins–>plugin–>executions–>execution

<!-- <goal>build-css</goal> -->

Dependencies are defined at the end of pom.xml. These are the bare minimum dependencies required for Liferay MVC Portlet. It includes portal-service, util-bridges, util-taglib, util-java, portlet-api, servlet-api and jsp-api.

The scope of all the above dependencies is provided means it would be available at runtime, so there is no need to put the JAR file of these dependencies in the generated WAR file.

How to build Liferay Maven Plugin

There are two ways.

  1. From eclipse
    1. Right-click on pom.xml, select Liferay–>Maven–>liferay:deploy task. On successful build, You will get logs in the console saying BUILD SUCCESS.
  2. From command prompt
    1. Open the command prompt and go up-to the plugin folder. Type mvn clean install liferay:deploy command.

Difference between these two.

If you observe, two additional commands – clean and install are given while building from the command prompt.

Clean command will clear the target folder before it starts building the plugin.

Install command will install your plugin into the maven repository. To cross-check, open Window RUN (press Window key + R) and type .m2

open repository –>com–>opensource–>techblog–>sample–>sample-mvc, and you will see your plugin with the snapshot version that you gave.

Open the 1.0.0-SNAPSHOT folder, and you will find your plugin war.

Note: your plugin would be available into the local maven repository (.m2) only when you run the install command while building it. Once it’s available in .m2, then only other plugin can consider your plugin for their dependencies.

  • You may check the target folder to see the generated WAR of your plugin.
  • If you need to clear the target folder, then give command mvn clean.
  • If you wish to install the generated WAR into the local maven repository, then give command mvn install.

Conclusively, the below infographics is the brief about creating Liferay MVC portlet with Maven.

liferay maven plugin - Create Liferay MVC Portlet with Maven

Summing Up

  • Liferay allows to create of a various plugin with maven from LDS or eclipse out of the box.
  • You have to install and configure maven first. Use Liferay plugin wizard to create a plugin with maven.
  • The project structure of the Liferay Maven plugin will be a little different than if it’s created by ANT.
  • There is no need for plugin-SDK for creating the Liferay Maven plugin. You need to give install command with maven to put your plugin into the local maven repository (.m2) so that it would be available to other plugins.
  • Creating the Liferay Maven plugin is straight forward, and you no need to place all your dependencies in your source code. Just define it in pom, and maven will take care of the rest.

And it’s done. Please provide your thought on creating Liferay MVC portlet with Maven in the comment section.

Download

Download

You can download the source from Git Hub Project.

 

Recommended For You

About the Author: Nilang

Nilang Patel is a technology evangelist who loves to spread knowledge and helping people in all possible ways. He is an author of two technical books - Java 9 Dependency and Spring 5.0 Projects.

2 Comments to “liferay maven plugin – Liferay MVC Portlet with Maven”

  1. Thanks for posting this blog, i am following your guideline to develop liferay-spring project. But at “Choose Portlet Framework” i do not see “Spring MVC” as option. This is required as from your blog post “https://www.opensource-techblog.com/2017/08/maven-spring-mvc-portlet.html”. I am using Eclipse Java EE IDE for Web Developers.
    Version: Luna Release (4.4.0)
    Build id: 20140612-0600
    Please let me know what i am missing

    1. Hello Sachin,

      If you are using correct eclipse / developer studio version, you will get that option. But it’s not visible, then don’t worry, just download the source code from that blog and create your portlet from there. Tool only creates the set of files automatically. In case if you are creating the spring mvc, then just do copy from the code that I attached in the blog.

      Regards
      Nilang

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.