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.

https://www.liferay.com/downloads/liferay-portal/available-releases

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)

http://ant.apache.org/bindownload.cgi

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)

http://www.liferaysavvy.com