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 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 Neon 3 version of eclipse.

Maven is very powerful tool which runs through POM (called Project Object Model). It’s complete project management tool rather just 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 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 most simplest and 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 home directory of maven. c:/maven in our case.

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

Maven profile

While working with maven, you can define set of project specific attributes which is 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 Maven profile for your project. You can get more about maven profile from this link.

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

You can relate the maven profile structure from following relation.

Liferay Maven Plugin - Maven Profile to Project structure

How to define Maven profile

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

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

Id :- shows the name by which maven profile is uniquely identify. 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 and paste the generated WAR files.

Activating the Maven profile

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 completion of </profiles> elements, just add below line.

Special Note :- You can define as many profile as you want. But you should make only one profile active. In case if you defined two profiles in <activeProfiles>, you won’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 active profile.

Configure Maven profiles in eclipse

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 moments, all the maven profiles (which are defined in maven settings.xml) will be available into eclipse.

Congratulation …. the ground work is done and we are ready to create liferay maven plugin. To make it simple, we will start with 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 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 plugin with exactly same name that you give here.

Unlike in 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 visible name of the portlet when you place it on 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 :-

Artifact is a file that get deployed on maven repository. Every artifact has version. Since your liferay plugin would also deployed on maven repository as plugin, you need to give artifact version of your plugin.

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

Just give artifact version as 1.0.0-SNAPSHOT. On releasing newer version of your plugin in 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 maven repository. This would be basically group the name as suggest. While giving group Id you need to follow certain naming conversion.

Active Profile :-

This is the profiles that we defined in maven settings xml file in above step. Select on right most icon (having small triangle – marked as 1 in below image) which will open the wizard to select profile as below.

liferay maven plugin - configure maven profile in eclipse

 

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

Location :-

Unlike Ant, Maven doesn’t force to put your liferay maven plugin to 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 eclipse workspace.

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

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

Plugin Type :-

It supports various liferay maven plugin type 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 thing as is and click on Next button. You will see below wizard.

Liferay Maven Plugin - Choose portlet framework

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

Portlet name and Display name are the same (But we can change) that we gave in previous screen.Choose the Liferay MVC (Default) as 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 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 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 appropriate change in portlet.xml located under WEB-INF.

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

Liferay Maven Plugin – POM Structure

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

Quick observation:-

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

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

Dependencies are defined at the end of pom.xml. These are 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 above dependencies are provided means, it would be available at runtime so no need to put JAR file of these dependencies in 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 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 command prompt.

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

Install command will install your plugin into 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 snapshot version that you gave.

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

Note: your plugin would be available into local maven repository (.m2) only when you run 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 local maven repository then give command mvn install.

Conclusively, 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 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 plugin with maven.
  • Project structure of liferay maven plugin would be little different than if it’s created by ANT.
  • There is no need of plugin-SDK for creating liferay maven plugin. You need to give install command with maven to put your plugin into local maven repository (.m2) so that it would be available to other plugin.
  • Creating 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 the rest.

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

Download

Download

You can download the source from Git Hub Project

 

Share This Post

Post Comment