Saturday, November 22, 2014

Liferay Plugins Development with MAVEN

  

Liferay Offers many ways to develop Plugin applications development we already much aware of Liferay IDE and ANT based plugins development



Liferay plugins development with MAVEN is also great choice for liferay developers.

What is MAVEN?

MAVEN is project build tool like ANT but its has more features than ANT when we build projects using MAVEN.

Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information.


Each Maven project consist pom.xml in project root directory where we will defined project build process.

POM is project object model is one of the build process system which describes about software project and POM will be specified as xml tag notation in pom.xml file.

pom.xml is blueprint of the project and it describes your project’s directories, required plugins, build sequence, and dependencies. The POM is your project’s sole descriptive declaration. Once you create the pom.xml file and invoke the build process.

Entire project structure defined in pom.xml so that we can manage entire project from single point and it is easy when we compare with ANT because ANT build process will be defined in different build.xml files. MAVEN projects are very easy to understand by developers

Maven provides an easy way to share artifacts (e.g., JARs, WARs, etc.) across projects via public repositories.

Liferay plugins SDK provides project templates to build sample Plugin applications in the same way Liferay provides maven archetypes from which we can create different sample liferay plugins applications.

Archetypes are the template of project structure and it consist of all required configurations,its files and directory structure.

We can have different archetypes like spring archetypes,struts archetypes and web application archetypes from this we can create basic project structure from there we can start development.

Same way liferay also have created different archetypes for each Plugin type so that we can create basic Plugin projects very easy.

Liferay Plugin Development with MAVEN

The following are are the required steps

Install JAVA
Install MAVEN
Install Liferay Portal Server Bundle
Install Liferay MAVEN Archetypes
Download Eclipse+Liferay IDE
Create Liferay Plugin Maven Project from Liferay IDE

Install JAVA

Liferay Java based portal so first we need to install Java in our machine download JDK 1.6 or later version and install.

we need to set important environment variables such as JAVA_HOME and need to edit path system variable and add java bin path(;%JAVA_HOME%/bin;). We need Java 6.0 JRE or greater.

Java Installation follow below link look into section “Install JDK and setting required environment variables (JAVA_HOME, path)”


Install MAVEN

We are using MAVEN based project building so first we need install MAVEN in machine and we also need to set environment variable like MAVEN_HOME/M2_HOME and edit the path then append MAVEN bin path.

Install MAVEN in Windows.

Download latest version of MAVEN archive file from apache maven download site


Download Maven 3.2.3 (Binary zip) archive file from above link

Extract zip file in any of desired location assume we have extracted in C drive then our maven home path will be C:\apache-maven-3.2.3

Now need to add M2_HOME and MAVEN_HOME system variables in the Windows environment, and point it to your Maven folder (C:\apache-maven-3.2.3)

Select Start, then right-select Computer --> Properties.

In the Advanced tab, click Environment Variables….

In the System variables section, click New

variable : M2_HOME

variable : MAVEN_HOME

Once we created two maven environment variables now we need to edit windows PATH variable then append Maven bin folder like ;%M2_HOME%\bin; so that you can run the Maven’s command everywhere.

In the System variables section, select your PATH variable and click Edit….

Append ;%M2_HOME%\bin; end of the existed path.

Now open windows command prompt then type following command then will shows maven version message otherwise there is problem in installation so need to recheck all steps.

mvn –version

Note:

semicolon in the path will separate the different path values so we should not forget to use semicolon.

Install MAVEN in Ubuntu

Open Ubuntu terminal

Run command sudo apt-get install maven, to install the latest Apache Maven.

It will take time to install all maven packages once it successfully done Run command mvn -version to verify your installation.

Manual Installation in Linux

Go apache MAVEN download site and download apache-maven-3.2.3-bin.tar.gz archive file


Extract in your desired location assume in opt directory then maven home path will be /opt/apache-maven-3.2.3

Now we need to configure maven environment variables in bash.bashrc or “/etc/profile”

bash.bashrc file will be available in /etc/bash.bashrc folder open in editor and add following configurations.

M2_HOME=/opt/apache-maven-3.2.3
PATH=$PATH:$M2_HOME/bin
export M2_HOME
export PATH

Run command mvn -version in the terminal to verify your installation

Install Liferay Portal Server Bundle

First we need to download portal server bundle based on developer choice. Once we downloaded bundle archive file then extract it in you desired location then you can see portal server bundle that consist application server with deployed liferay portal.


Liferay Portal Server is actual environment to run liferay Plugin applications. Liferay Portal Run time come up with different application servers such as tomcat,jboss,glashfish, jetty, geromino, JOnAS and resin.

Liferay provided these run time bundle with different server so that we can use any one based on developer choice.

Assume we will use tomcat bundle so download liferay-portal-tomcat-6.2-ce-ga2.zip from above location.

Now extract zip file in of your desired location now we are ready with liferay portal tomcat server.

Liferay Server Bundle Consist Application server and Deployed Liferay Portal Application. When we observed server deployment directory(for tomcat/webapps) we can see deployed Liferay Portal application with name ROOT.

Install Liferay MAVEN Archetypes

We are developing plugins with maven so we need to install liferay maven archetypes. Liferay maven archetypes are like project templates consist all required configurations and its files.

Download Liferay Portal Maven archive file(liferay-portal-maven-6.2-ce-ga2.zip) from following location


Now extract file on any of your desired location now we need to install liferay maven archetypes.

To install maven archetypes first we need to install ANT tool in our machine because maven archetypes used ANT build mechanism that is why we should install ANT tool

Install maven archetypes is nothing but we will place all requires liferay maven plugins and jar files in the local maven repositories that is (${USER_HOME}/.m2/repository)

Install ANT

Go to Apache ant site and download latest ANT (.zip archive: apache-ant-1.9.4-bin.zip)


Once you downloaded zip file extract in your desired location and we need to set ANT system environment variable in our machine.

We need to create ANT_HOME and we need to append ANT bin path in “path” environment variable.

Set ANT Environment Variable in Linux

Assume We have extracted ANT in the location “/opt/apache-ant-1.9.4”
Now ANT_HOME is “/opt/apache-ant-1.9.4” and ANT bin path is “$ ANT_HOME/bin”

Generally in the Linux we will use “.profile” or “bash.bashrc” file to set all environment variables. Now open .bash_profile file in editor and add following configuration then save it.

export ANT_HOME=/opt/apache-ant-1.9.4
export PATH=$PATH:$ANT_HOME/bin

Now open Linux Terminal type “ant -version” then it show ant version now you have successfully installed ANT.

Set ANT Environment Variable in Windows

Select Start, then right-select Computer --> Properties.

In the Advanced tab, click Environment Variables.

In the System variables section, click New

Set the ANT_HOME variable:

Variable name: ANT_HOME
Variable value: [Ant installation path] (e.g., C:\apache-ant-[version])

Click OK.

Also in the System variables section, select your path variable and click Edit….

Insert ;%ANT_HOME%\bin; end of the existed path value and click OK.

Click OK to close all system property windows.

Open a new command prompt “ant -version” then it show ant version now you have successfully installed ANT.

Now we are ready with ANT tool

Now Install Liferay MAVEN Archetypes into Local Maven Repository(${USER_HOME}/.m2/repository)

Open command prompt/terminal based on your OS issue the following command
Navigate to liferay-portal-maven-6.2-ce-ga2 then issue following command

ant install

Console shows output from the artifacts being installed from the Liferay Maven package into your local repository, typically located in your ${USER_HOME}/.m2/repository directory. Local repository now contains the Liferay artifacts required to build Liferay plugins

Download Eclipse+Liferay IDE

Well as of now we are ready with MAVEN archetypes installed in maven local repository and Liferay Portal Server now we need a development IDE to create Liferay MAVEN Project.

Generally we need eclipse , Liferay IDE ,MAVEN Eclipse Plugin,Liferay IDE MAVEN Plugin.

The following are the required eclipse plugins to support Liferay MAVEN Environment in Eclipse.

m2e-core (Maven integration for Eclipse)
m2e-wtp (Maven integration for WTP)
m2e-liferay plugin

All together will be available in single package when we download Eclipse Liferay IDE from Liferay downloads.

Go through following link


Select Other download drop-down select Eclipse Luna + Liferay IDE 2.2.0-ga1 option based on your OS and its Bits

Now extract archive file in desired location then you can see root directory that is eclipse if you go to root directory then you can see eclipse icon when we double click on icon then eclipse will be started.

Create Liferay Plugin Maven Project from Liferay IDE

before start development now we will notice following things

Assume as follows

Create directory give name LiferayMaven in “/opt” then workspace path /opt/ LiferayMaven

Auto Deploy Directory: “/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/deploy ”

App Server Deploy Directory:”/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps ”

App Server Lib Global Directory:”/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/lib/ext ”

App Server Portal Directory:”/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps/ROOT ”

Liferay Version: 6.2.1

Start eclipse and select LiferayMaven is default work space.

Configure Liferay Portal Run Time In Liferay IDE

Eclipse Window → Preferences → Server → Runtime Environments.

Click Add to add a new Liferay runtime; find Liferay v6.2 (Tomcat 7) under the Liferay, Inc. category and click Next.

Click Browse and select your liferay-portal-6.2.x/tomcat-7.x (/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42)directory.

Select Run Time JRE
Click Finish; you should see your Liferay portal runtime listed in Preferences → Server → Runtime Environments.
Click OK to save your runtime preferences

Create Liferay Plugin Maven Project

Go liferay IDE icon and Click on “Create New Liferay Plugin Project”

Now it will launch Liferay Plugin Project Dialog window

Now fill all the fileds with appropriate values as follows

Project Name: liferay-sample-portlet

Project Display Name : Liferay Sample Portlet

Tick the check box “use default location” for Location

Build Type: Maven(liferay-maven-plugin)

Artifact version: keep default one

Gropuid: com.liferay.sample

Active Profile:

Click the icon “Create New Maven Profile Based on Liferay Run Time”

it will open another dialog window ask information as follows
Liferay Run Time: Liferay v6.2 CE(Tomcat)
Liferay Version: 6.2.1
Check the profile location radio button as “project pom.xml”

The following is Maven Profile Dialog


Then click on OK it will create maven profile with given values in project pom.xml

Now finally Liferay Plugin Project Dialog Look like as follows after fill all the thing



Now click on Next then you can move to next step there check the radio button Liferay MVC portlet then click on finish


Once we finish then it will prompt another Liferay Portlet dialog window and fill the details as follows

source folder: use default
check the Create New Portlet Radio button
Portlet class: you choice
Java Package : your choice
Super Class: MVC portlet


Once we provided the information click on finish button then Plugin portlet project will be created.

The following is created Liferay Maven Plugin Portlet Project




In the project explorer you can see the project and every maven project have one xml file called pom.xml file there all build process will be defined.

Now click on pom.xml file then you can see default all build configuration like plugins definitions, configuration and dependencies information.

Now do the following changes in project pom.xml file

Comment/remove following lines

<execution>
<phase>generate-sources</phase>
<goals>
<goal>build-css</goal>
</goals>
</execution>

Find the following configuration

<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>

Now replace above configuration with below configuration

<configuration>
<autoDeployDir>/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/deploy</autoDeployDir>
<appServerDeployDir>/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps</appServerDeployDir>
<appServerLibGlobalDir>/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/lib/ext</appServerLibGlobalDir>
<appServerPortalDir>/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps/ROOT</appServerPortalDir>
<liferayVersion>6.2.1</liferayVersion>
<pluginType>portlet</pluginType>
</configuration>

Note:

the above details are based on where your portal server resided.

find following tag and replace with version number

<version>${liferay.maven.plugin.version}</version>

Replace as

<version>6.2.1<version>

Change following tag in all dependencies from <version>${liferay.version}</version> to <version>6.2.1</version>

Add Other important liferay dependencies

<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-client</artifactId>
<version>6.2.1</version>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-impl</artifactId>
<version>6.2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-pacl</artifactId>
<version>6.2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-service</artifactId>
<version>6.2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-web</artifactId>
<version>6.2.1</version>
<type>war</type>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-bridges</artifactId>
<version>6.2.1</version>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-java</artifactId>
<version>6.2.1</version>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-slf4j</artifactId>
<version>6.2.1</version>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-taglib</artifactId>
<version>6.2.1</version>
</dependency>

Note:

Above all dependencies should enclose by <dependencies></dependencies> tag.

Finally liferay Plugin portlet project pom.xml as follows

<?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.liferay.sample</groupId>
<artifactId>liferay-sample-portlet</artifactId>
<packaging>war</packaging>
<name>liferay-sample-portlet Portlet</name>
<version>1.0.0-SNAPSHOT</version>
<build>
<plugins>
<plugin>
<groupId>com.liferay.maven.plugins</groupId>
<artifactId>liferay-maven-plugin</artifactId>
<version>6.2.1</version>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>build-css</goal>
</goals>
</execution>
</executions>
<configuration>
<autoDeployDir>/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/deploy</autoDeployDir>
<appServerDeployDir>/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps</appServerDeployDir>
<appServerLibGlobalDir>/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/lib/ext</appServerLibGlobalDir>
<appServerPortalDir>/opt/LiferayMaven/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps/ROOT</appServerPortalDir>
<liferayVersion>6.2.1</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>6.2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-bridges</artifactId>
<version>6.2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-taglib</artifactId>
<version>6.2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-java</artifactId>
<version>6.2.1</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>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-client</artifactId>
<version>6.2.1</version>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-impl</artifactId>
<version>6.2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-pacl</artifactId>
<version>6.2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-service</artifactId>
<version>6.2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>portal-web</artifactId>
<version>6.2.1</version>
<type>war</type>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-bridges</artifactId>
<version>6.2.1</version>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-java</artifactId>
<version>6.2.1</version>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-slf4j</artifactId>
<version>6.2.1</version>
</dependency>
<dependency>
<groupId>com.liferay.portal</groupId>
<artifactId>util-taglib</artifactId>
<version>6.2.1</version>
</dependency>
</dependencies>
</project>

Now we have done all the required configuration in project pom.xml now we can deploy project.

Deploy Liferay Plugin Maven Project

Open command prompt or terminal and go to newly created liferay Plugin project location its generally in eclipse work space(LiferayMaven) then issue following command.

mvn package


once build was successful then issue following command to deploy into portal server

mvn liferay:deploy

now portlet will be deployed into portal and you can see build success message in the console


If portal already start then you can see Plugin deployment information in server log file.

Download sample liferay maven Plugin from below link when you use this project please make sure you should installed Liferay Maven Archetypes in your local and you have to change server configuration and versions information in the pom.xml file.

https://sourceforge.net/projects/meeralferay/files/SampleLiferayMaven/

 The following pom.xml for liferay maven plugin portlet with liferay-portal-maven-6.2-ce-ga4

 <?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.liferay.sample</groupId>
<artifactId>liferay-sample-portlet</artifactId>
<packaging>war</packaging>
<name>liferay-sample-portlet 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>
<profiles>
<profile>
<id>Liferay-v6.2-CE-(Tomcat-7)</id>
<properties>
<liferay.version>6.2.3</liferay.version>
<liferay.maven.plugin.version>6.2.2</liferay.maven.plugin.version>
<liferay.auto.deploy.dir>C:\MeerPrince\LiferayWorkSpace\bundles\deploy</liferay.auto.deploy.dir>
<liferay.app.server.deploy.dir>C:\MeerPrince\LiferayWorkSpace\bundles\tomcat-7.0.42\webapps</liferay.app.server.deploy.dir>
<liferay.app.server.lib.global.dir>C:\MeerPrince\LiferayWorkSpace\bundles\tomcat-7.0.42\lib\ext</liferay.app.server.lib.global.dir>
<liferay.app.server.portal.dir>C:\MeerPrince\LiferayWorkSpace\bundles\tomcat-7.0.42\webapps\ROOT</liferay.app.server.portal.dir>
</properties>
</profile>
</profiles>

</project>

Important Points

The configuration in pom.xml will be changed based on your environment like version number, server configuration and dependencies versions.

The above maven setup we have installed maven archetypes in our local repository that is /.m2/repository.

http://sourceforge.net/projects/lportal/files/Liferay%20Portal/6.2.1%20GA2/We have created liferay maven project from Liferay IDE tool without Liferay IDE also we can create liferay plugins from command prompt/terminal.

We have create Pluginv portlet project apart from that we can also create all liferay plugins like hook,web,ext,theme and layouttpl from liferay maven archetypes.

Author
Meera Prince
Liferay Top Contributor Award Winner(2013,2014)

Thursday, November 20, 2014

Liferay Plugins Development with Plugins SDK+ANT Quick Notes

  

Liferay have given many options to develop liferay Plugin applications among that one of the developer choice is Liferay Plugins SDK with ANT tool.

Plugins SDK is liferay standard development Kit to develop liferay Plugin applications and its consist of all required to files and library files to develop liferay applications.

To start development with Plugins SDK we need ANT ,Liferay Portal Server Bundle,Plugins SDK and Text Editor

The following steps are required

Install JDK 1.6 or above version.
Install Portal Server Bundle
Install ANT
Install Plugins SDK
Plugins SDK Configuration
Create Plugin Applications with Liferay SDK

Install JDK 1.6 or above version

Liferay portal is Java based portal so first we need to install JDK .we need to set important environment variables such as JAVA_HOME and need to edit path system variable and add java bin path(;%JAVA_HOME%/bin;). We need Java 6.0 JRE or greater.

Install Portal Server Bundle

First we need to download portal server bundle based on developer choice. Once we downloaded bundle archive file then extract it in you desired location then you can see portal server bundle that consist application server with deployed liferay portal.


Liferay Portal Server is actual environment to run liferay Plugin applications. Liferay Portal Run time come up with different application servers such as tomcat,jboss,glashfish, jetty, geromino, JOnAS and resin.

Liferay provided these run time bundle with different server so that we can use any one based on developer choice.

Liferay Server Bundle Consist Application server and Deployed Liferay Portal Application. When we observed server deployment directory(for tomcat/webapps) we can see deployed Liferay Portal application with name ROOT.

Install ANT

Liferay Development need ANT tool to build and deploy applications. Plugins SDK developed using ANT scripts so that first we need to install ANT tool to start development.

Go to Apache ant site and download latest ANT (.zip archive: apache-ant-1.9.4-bin.zip)


Once you downloaded zip file extract in your desired location and we need to set ANT system environment variable in your machine.

We need to create ANT_HOME and we need to add ANT bin path in “path” environment variable.

Set ANT Environment Variable in Linux

Assume We have extracted ANT in the location “/java/apache-ant-1.9.4”
Now ANT_HOME is “/java/apache-ant-1.9.4” and ANT bin path is “$ ANT_HOME/bin”

Generally in the Linux we will use “.bash_profile” or “bash.bashrc” file to set all environment variables. Now open .bash_profile file in editor and add following configuration then save it.

export ANT_HOME=/java/apache-ant-<version>
export PATH=$PATH:$ANT_HOME/bin

Now open Linux Terminal type “ant -version” then it show ant version now you have successfully installed ANT.

Set ANT Environment Variable in Windows

Select Start, then right-select Computer --> Properties. 

In the Advanced tab, click Environment Variables.

In the System variables section, click New

Set the ANT_HOME variable:

Variable name: ANT_HOME
Variable value: [Ant installation path] (e.g., C:\apache-ant-[version])

Click OK. 

Also in the System variables section, select your path variable and click Edit….
Insert %ANT_HOME%\bin; after %JAVA_HOME%\bin; and click OK. 

Click OK to close all system property windows. 

Open a new command prompt “ant -version” then it show ant version now you have successfully installed ANT.

Plugins SDK Configuration

 

Plugins SDK Configuration are like portal server and other needed information,we need to specify in the “build.properties” file and the file consist with default configurations. This file is available in Plugins SDK root directory.

We need to edit this file with our configurations. But we should not edit “build.properties” instead of that we need to clone this file in same location and change name as “build.[username].properties”

Lets say system user name is “meeraprince” then properties file will be “build.meeraprince.properties”

The cloned “build.meeraprince.properties” already have default build configurations and we need to edit these configurations according to our local environment.

Edit this file and find the following lines and change the paths according to your settings.

app.server.type=[the name build.properties uses for your application server type]
app.server.parent.dir=[the directory containing your Liferay Server bundle]
app.server.tomcat.dir=[the directory containing your application server] 

Assume we are using Liferay Portal Tomcat Bundle and the bundle location is “D:/workspace/liferay-portal-6.2” folder then we need to specify the following lines in the properties file.

app.server.type=tomcat
app.server.parent.dir= D:/workspace/liferay-portal-6.2
app.server.tomcat.dir=${app.server.parent.dir}/tomcat-7.0.42 

app.server.parent.dir we can call it as Liferay Home Directory in our case “D:/workspace/liferay-portal-6.2” is Liferay Home Directory.

Plugins SDK consist many files ,required directories and these are required to develop plugins applications.

The following are the different files and required directories in Plugins SDK

Each directory in the Plugins SDK contains build xml file and command scripts for creating new plugins of that type. Here is the directory structure of the Plugins SDK.

liferay-plugins-<version>/ - Plugins SDK root directory. 

clients/ - client applications directory. 

dist/ -it consist of all plugins applications generated .war files 
 
ext/ - consist created “ext” plugins applications.

hooks/ - consist created hook plugin application 

layouttpl/ - consist created layout templates directory.

lib/ - commonly referenced libraries like all jar file required to development of plugins. 

misc/ - development configuration files. Example, a source code formatting specification file. 

portlets/ - consist created portlet plugins applications.

themes/ - consist created themes plugins directory.

tools/ - plugin templates and utilities to created basic Plugin application structure. 

webs/ - web plugins directory. 

build.properties - default SDK properties. 

build.<username>.properties - (optional) override SDK properties. 

build.xml – ANT build file consist all applications build information. 

build-common.xml - contains common targets and properties referenced throughout the SDK. 

build-common-plugin.xml - contains common targets and properties referenced by each plugin. 

build-common-plugins.xml - contains common targets and properties referenced by each plugin type. 

When we create Plugin applications then it will be created in respective directory which I specified above.Each created Plugin application consist “build.xml” file in project root directory and this “build.xml” file have other build files references to define build process.

Each plugins application consist different ANT targets to compile,package and deploy applications. We need to navigate to respective project root directory and need to invoke these targets then it will perform respective tasks on Plugin project.

When we run “ant deploy” target from Plugins SDK root directory then all Plugin applications will be deployed.

When we run “ant deploy” target from portlet directory then all Plugin portlets will be deployed same we can apply this for “ext,themes, layouttpl and hooks”.

The following are important ANT targets.

ant compile : Compile all java class files and make it as .class files in the Plugin applications.

ant clean : cleans the files created by the invocations of the compilation, archiving, and deployment targets.

ant deploy : this target deploy Plugin application means compile,package war file placed in deploy directory of server.

ant build-service : builds the service layer for a Plugin, using Liferay Service Builder.
ant war : its just packaged Plugin application as war file and placed in dist directory.

Note:

Generally ant targets are depends on other targets to complete the complex task. Lets say when we run “ant deploy” then its automatically invoke the ant compile and ant war targets to complete the deploy task.

Create Plugin Applications with Liferay SDK

Liferay Plugins SDK is providing command line user interface to create plugins projects. We already know tools directory consist of template and these commands will use templates and create basic plugins applications with required files,folders and its configurations.

Based on our Plugin type we need to navigate to respective directory form command prompt then need to execute project creation command and these commands are different for each Plugin type.

When you look into Plugin type directory such as portlets,themes,hooks,layouttpls,webs and ext then you can see two files such as “create.bat” and “create.sh”. When you open these files in text editor then you can find respective Plugin project creation command.

create.bat is for windows environment and we need to use this when we are working with Windows OS.

create.sh is for Linux environment and we need to use this when we are working with Linux OS.

Assume we want develop portlet plugin application then we need to navigate to portlet directory through the command prompt/Linux terminal from there we need to issue the portlet creation command.

On Linux and Mac OS X, enter 

./create.sh hello-world "Hello World" "mvc"

On Windows, enter 

create.bat hello-world "Hello World" "mvc"
   
The first hello-world is your portlet id. A new directory will be created based on the portlet id in the portlet directory.

The second "Hello World" is the portlet's display name. The quotation marks are only needed because there is a space in the display name.

A third value can be passed to specify the portlet framework to use. Valid values "jsf", "icefaces", "liferay_faces_alloy", "mvc", "primefaces", "richfaces", or "vaadin". The default value is "mvc". 
 
Now you can go to portlets directory( liferay-plugins-<version>/portlets) and open newly created portlet project then you can see all required files, folders and its configurations. Now open file in editor you can edit the files as for your need.Once we done with all editing of files then we need deploy plugin portlet using “and deploy” target.

Now go to newly created Plugin portlet project directory from command prompt then issue ant target that is “ant deploy” then portlet will be deployed in the portal server.

After successful deployment you can see message like portlet for hello-world-portlet is available for use. If not, double-check your configuration.

The same process you can apply for all other Plugin types such as themes,webs,hooks,ext and layouttpl.

Hooks

Linux OS
./create.sh hello-world "Hello World"

Windows OS
create.bat hello-world "Hello World"

Layouttpl

Linux OS
./create.sh hello-world "Hello World"

Windows OS
create.bat hello-world "Hello World"

Theme

Linux OS
./create.sh hello-world "Hello World"

Windows OS
create.bat hello-world "Hello World"

Whats is Plugins SDK?

Plugins SDK is liferay applications development kit consist of libraries,files and Plugin templates. with this we can create and develop liferay plugins.
Plugins SDK provided command bases user interface i.e. ANT command and its targets to create and develop liferay plugins. 

What is Portal Server Run Time?

Liferay Portal Run time is run time environment run liferay Plugin application and it consist of application server with deployed liferay portal along with HSQL database and one deployment directory i.e deploy.

Liferay Portal Run time come up with different Application server developer can choose any one among those(tomcat,jboss, glashfish, jetty,geromino, JOnAS and resin).

The portal run time available as bundle and no more configuration is required we can directly start server and access liferay portal.

What are the minimum Artifacts required for Liferay Application Development with Plugins SDK?

Liferay Portal Server Bundle
JRE/JDK
Liferay Plugins SDK
ANT
One Text Editor

Where we need to configure liferay server information?

We will use build.properties file available in Plugins SDK but we should not modify these properties so we need to clone build.properties file and change name as build.UserName.properties then modify the configurations

Can i modify build.properties file directly?

Yes you can modify but its not recommended process instead of that simply clone file in same location and change name as build.userName.properties

If suppose system user Name is meeraprince then what is the name of cloned properties file?

build.meeraprince.properties

What is server configuration in builld.userName.properties file for tomcat?

app.server.type = tomcat
app.server.parent.dir = /opt/LiferayWorkSpace62/bundles
app.server.tomcat.dir =${app.server.parent.dir}/tomcat-7.0.42
app.server.tomcat.deploy.dir =${app.server.parent.dir}/tomcat-7.0.42/webapps
app.server.tomcat.lib.global.dir =${app.server.parent.dir}/tomcat-7.0.42/lib/ext
app.server.tomcat.portal.dir =${app.server.parent.dir}/tomcat-7.0.42/webapps/ROOT

where is the hot/auto deployment directory?

The directory name is deploy which is available in liferay portal server run time bundle.
Example: liferay-portal-6.2-ce-ga2/deploy or bundles/deploy

Can i change hot deployment directory location?

Yes you can change but you need to configure in build.username.properties with below property.
app.server.parent.dir = /opt/WorkSpace/bundles
auto.deploy.dir = ${app.server.parent.dir}/deploy

What is app.server.parent.dir ?

app.server.parent.dir is directory where portal server available
example: in our case tomcat7.x server available in the directory WorkSpace/bundles
Note: these directory is your choice but make sure portal server should be available specifies location .please provides fully qualifies path.

What is Liferay Home?

Liferay Home directory and app.server.parent.dir are same where liferay portal servers are placed.

How can I change liferay database configurations?

Liferay Data base configurations are placed in portal-ext.properties file and this file should be placed on Liferay Home/ app.server.parent.dir directory.Liferay Support Many Databases so we can configure any one that specified by Liferay.

What are the databased supported by liferay?

db2,derby,hypersonic,ingres,mysql,oracle,postgresql,sqlserver,sybase

Suppose my database Mysql then how could configure in Liferay?

We need to configure Mysql database connection settings in portal-ext.properties with following properties and this file should be available in Liferay Home/ app.server.parent.dir directory.

# MySQL


jdbc.default.driverClassName=com.mysql.jdbc.Driver
jdbc.default.url=jdbc:mysql://localhost/lportal? useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
jdbc.default.username=
jdbc.default.password=

Note:

When we change database then we need to add respective jdbc implementation jar file in sever global lib directory. For MySQL we can find mysql.jar file. Fortunately liferay already added mysql.jar file in server global lib directory.

What is Server Global lib directory?

Server global lib directory consist of all jar files those are required by applications which are deployed in server. When we place any jar file in server global lib directory then it will be available to all applications. For tomcat tomcat-7.0.42/lib is server global lib directory.

What is liferay portal global lib directory?

Liferay portal global directory consist of all jar files which is used by liferay portal and all liferay deployed Plugin applications. If any library jar file placed in liferay global lib directory then it will be accessible to liferay portal and all Plugin applications. This directory name is ext which is sub directory of tomcat server lib directory that is /tomcat-7.0.42/lib/ext

If my data base then how can configure it in Liferay?

Liferay Data base configurations are placed in portal-ext.properties file and this file should be placed on Liferay Home/ app.server.parent.dir directory. The following are the Oracle Database connection properties.

# Oracle 
 
jdbc.default.driverClassName=oracle.jdbc.driver.OracleDriver
jdbc.default.url=jdbc:oracle:thin:@localhost:1521:xe
jdbc.default.username=lportal
jdbc.default.password=lportal 
 
Here we need to add oracle jdbc implementation ojdbc6.jar file in server global lib directory

What is portal-setup-wizard.properties?

portal-setup-wizard.properties file is properties file this will be created when we start liferay portal for first time.
When we access liferay portal for first time we will get some configuration pages such as admin user registration and liferay database configurations and all these configuration will be stored in portal-setup-wizard.properties.

Where portal-setup-wizard.properties file will be created?

portal-setup-wizard.properties will be created in Liferay Home/ app.server.parent.dir directory
Example properites stored in portal-setup-wizard.properties

admin.email.from.name=Test Test
liferay.home=/opt/LiferayWorkSpace62/bundles
admin.email.from.address=test@liferay.com
setup.wizard.enabled=false

How many places can I configure liferay database connection details?

We can use portal-setup-wizard.properties or portal-ext.properties and make sure both should available Liferay Home/ app.server.parent.dir.
portal-setup-wizard.properties will created automatically by liferay when we access liferay portal first time and portal-ext.properties we need create to override existed portal properties.

Is this mandatory portal-ext.properties file should be in Liferay Home/ app.server.parent.dir directory?

No. We can also placed portal-ext.properties in portal classes directory i.e. /tomcat-7.0.42/webapps/ROOT/WEB-INF/classes.

But use Liferay Home/ app.server.parent.dir is best practice to place portal-ext.properties file.

If place portal-ext.properties all above three places then what could be the my configuration?

Liferay will finally read the properties from Liferay Home/ portal-ext.properties.

How does plugins are packaged?

All liferay plugins will be packaged as .WAR file and these war files places on dist directory it will be available in plugins SDK directory.

What is the ANT target to deploy liferay plugins?

We will use ant deploy target and its default target for each liferay Plugin application. We can also use ant direct-deploy too.

Where is application build process will be defined?

In plugins SDK we can find buid.xml file where all liferay Plugin application build process will be defined. This file available in Plugins SDK root directory.

Do i need to modify liferay plugins build file?

No. all build process defined by liferay we never get chance to change those file.

What is difference between ant war and ant deploy targets?

Ant war target do the job like compile and package Plugin application as .WAR file and places .war file dist directory.
 
Ant deploy target do the job like compile and package plugins application as .war file place .WAR file in dist directory in addition to that it will copy .WAR file into liferay portal deploy(${app.server.parent.dir}/deploy) directory so that it makes Plugin application available to deployment.
  
What is Plugin portlet creation command? 

On Linux and Mac OS
./create.sh hello-world "Hello World" "mvc"
On Windows
create.bat hello-world "Hello World" "mvc"

How many input option will take portlet creation command?

Three input options and third one is optional. The default option value is “mvc”

What are the valid inputs values for portlet create command third input option?

A third value can be passed to specify the portlet framework to use. Valid values "jsf", "icefaces", "liferay_faces_alloy", "mvc", "primefaces", "richfaces", or "vaadin". The default value is "mvc".

What are the create commands for theme,layouttpl,web,ext and hook?

Linux OS
./create.sh hello-world "Hello World"
Windows OS
create.bat hello-world "Hello World"
all are take only 2 input option for create command except portlet note it third input option always optional for portlet.

What are the main directories in Plugins SDK?

Clients,dist, ext, hooks, layouttpl, lib, misc, portlets, themes, tools and webs

What are build files available in Plugins SDK?

build.xml, build-common.xml, build-common-plugin.xml and build-common-plugins.xml


What are other important properties in build.properties file?
 
database.name=lportal
database.types=db2,derby,firebird,hypersonic,informix,ingres,interbase,jdatastore,mysql,oracle,postgresql,sap,sqlserver,sybase
#javac.compiler=modern
javac.compiler=org.eclipse.jdt.core.JDTCompilerAdapter
lp.version=6.2.0

Note:
any of build properties should be override by the build.[username].properties file and this file should be in Plugins SDK root directory.

Author
Meera Prince
Liferay Top Contributor Award Winner(2013,2014)
Subscribe to: Comments ( Atom )

Recent Posts

Recent Posts Widget

Popular Posts