Introduction #

The Liferay Plugins SDK is a development environment that helps in the development of all types of plugins for Liferay including:

  • Portlets
  • Themes
  • Layout templates

This development environment is based on the popular Apache Ant tool so that it can be integrated with all the popular IDEs or used directly from the command line.

Preparation #

The preparation can be done in a few minutes. Follow these steps:

  1. Download the Plugins SDK from http://www.liferay.com/web/guest/downloads/additional
  2. Unzip the ZIP file to your destination of choice. I'll refer to it from now on as $PLUGINS_SDK
  3. Create a file named $PLUGINS_SDK/build.${user.name}.properties where ${user.name} is the name of the user in your system. In that file you can overwrite the values of any of the properties in the $PLUGINS_SDK/build.properties file. Some common properties that are overridden (with example values) are:
    1. app.server.dir=/my-dir/appservers/liferay-portal-tomcat-jdk5-trunk
    2. auto.deploy.dir=${user.home}/liferay/deploy
    3. app.server.lib.portal.dir=/my-dir/liferay/trunk/portal-web/docroot/WEB-INF/lib
    4. app.server.portal.dir=/my-dir/liferay/trunk/portal-web/docroot
    5. javac.compiler=modern
  4. Install Apache Ant and make sure that ANT_HOME/bin is in your path to be able to build and package your work.
  5. On Linux and Mac systems unzipping the archive will not make the enclosed shell scripts executable. You need to execute (e.g.)
    chmod +x create.sh
    before being able to use it as documented below

Working with plugins #

Common tasks #

The most common tasks can be performed executing ant tasks. Those tasks can be executed either from the root directory to apply to all the plugins, from the themes|portlets|layouttpl directories to apply only to the themes, portlets or layout templates, or within the directory of a single plugin to apply only to it.

Here are the most common tasks along with the associated ant target

  • Compile the sources (applicable only to portlets):
 ant compile
  • Create a WAR file of the plugin
 ant war
  • Deploy the plugin (to the path confibured in the auto.deploy.dir property of the $PLUGINS_SDK/build.${user.name}.properties file)
 ant deploy

Creating a new theme #

  • In the $PLUGINS_SDK/themes folder run (on windows):

 create newtheme "My New Theme" 
or, on Linux/Mac:
./create.sh newtheme "My New Theme"
(Where newtheme is the name of the folder for your theme and "My New Theme" the display name)

  • Navigate to the newly created $PLUGINS_SDK/themes/newtheme/_diffs and add some customizations to the default theme.
  • Issue 'ant all' in the $PLUGINS_SDK/themes folder to build and deploy.
  • Log in into Liferay and check out your new creation.

If you want your theme to be developed from another existing theme, you can modify the file build.xml (inside the folder of the theme) and change the parent.theme attribute to the id of the theme you want it to be copied from (for example, classic) and then deploy again. Your modifications to the theme should go into the custom.css file in the _diffs folder. All the changes you make in other css files will be overwritten when you deploy the theme again.

Creating a new portlet #

  • In the $PLUGINS_SDK/portlets folder run (on windows):

 create newportlet "My New Portlet" 
or, on Linux/Mac:
 ./create.sh newportlet "My New Portlet" 
(Where newportlet is the name of the folder for your portlet and "My New Portlet" the display name)

  • Issue 'ant all' in the $PLUGINS_SDK/portlets folder to build and deploy
  • Log in into Liferay and check out your new creation

Example plugins #

Liferay uses the Plugins SDK to develop the plugins that come with Liferay. This includes a lot of examples that you may want to use as a basis for your development. You can download them from Sourceforge and also browse and download the code in Liferay's Subversion repository

Plugin development with Eclipse #

If you use eclipse and develop more plugins, you will find out that the current directory structure of the SDK is not the best solution for you. Fortunately it's not a hard thing to make it comfortable.

SDK preparation #

First, prepare the SDK as described above (Preparation steps 1-5), then create a new Eclipse Java project from the SDK directory (creating a new Java Project and copy the SDK there is one working solution).

Put all the jar files found in the /lib directory of the new plugin to the build path and export it.

The SDK is ready to use.

New plugins #

You can create the new plugins as written in the Common Tasks section. But after doing so, move the new directory to the same level in the structure as the sdk. Create a new plugin from it, again, add the liferay-plugin-sdk project to the build path.

The build.xml files work only in the other structure so we need to change them. Examples:

Theme plugin:

<?xml version="1.0"?>

<project name="theme" basedir="." default="deploy">
	<property name="project.dir" value="../liferay-plugins-sdk" />
	<import file="${project.dir}/themes/build-common-theme.xml" />
	<property name="theme.parent" value="_styled" />
</project>

Layout plugin:

<?xml version="1.0"?>

<project name="layouttpl" basedir="." default="deploy">
	<property name="plugin.version" value="1" />
	<property name="project.dir" value="../liferay-plugins-sdk" />
	<import file="${project.dir}/layouttpl/build-common-layouttpl.xml" />
</project>

Hooks:

<?xml version="1.0"?>

<project name="hook" basedir="." default="deploy">
	<property name="project.dir" value="../liferay-plugins-sdk" />
	<import file="${project.dir}/hooks/build-common-hook.xml" />
</project>

Known issues with this structure #

  • build builds the war files into the plugin-sdk project's dist directory
  • hard to create new projects (should create eclipse project templates for these plugins)
  • SDK should be an Eclipse project in Subversion already
2 Attachments
177251 Views
Average (2 Votes)
The average rating is 4.5 stars out of 5.
Comments
Threaded Replies Author Date
Hi This is very useful page to develop portal... Raghu N N October 20, 2008 2:28 PM
I am also receiving this error when attempting... matt baker October 21, 2008 11:23 AM
Same problem. Obviously buildfile is lacking.... Stefan Kiefer October 24, 2008 1:44 AM
I get the same error message. Is there a way to... Eetu Blomqvist October 24, 2008 6:05 AM
OK, there is a good hint in the Forum with a... Stefan Kiefer October 24, 2008 6:51 AM
The portlet.zip file in question fixes the... Randy Brandenburg October 29, 2008 6:11 AM
What about Clients, Hooks and Webs plugin? ... Ivano Carrara November 5, 2008 2:32 AM
Idem problem is for th theme.zip file at... Alban KOM. November 14, 2008 1:16 AM
Idem problem is for the theme.zip file at... Alban KOM. November 16, 2008 8:05 AM
Hi, please did you solve the problem i have the... imen imen taieb July 7, 2009 8:58 AM
SDK vs EXT. Not to start a huge debate or... John Joseph Ryan December 26, 2008 5:55 AM
I'm trying using Suse linux but the command... Marco Guastalli March 25, 2009 9:58 AM
I'm using Windows and have the same problem.... S F November 18, 2010 7:46 AM
Found the problem. In properties file (in our... S F November 18, 2010 8:12 AM
Okay I just want to check the values here. I... Hoppy Patterson May 10, 2009 3:35 PM
I was getting the build failed message like a... Beau Davis June 26, 2009 6:24 AM
Hi All, Has anyone try to add a custom code to... Patrick Roch July 19, 2009 3:11 PM
I have setup the Plugins SDK to override... Sandesh K July 27, 2009 2:00 AM
I'm following the Jonas Yuan book, but... Pablo M Mino September 2, 2009 2:39 PM
What is the status of Maven ? Bruno Vernay June 23, 2010 1:19 AM
PLEASE HELP ME OUT , I CANT UNDERSTANT THIS... Sudhakar T July 23, 2010 9:50 AM
Sudhakar you have to use the Ant build... Tanweer Ahmed Ansari July 26, 2010 3:29 AM
"ant war" does not create war file. Fawad Ali August 8, 2010 8:46 AM
'ant all' is not working in themes and portlets... Fawad Ali August 8, 2010 9:35 AM
Dear All, I am new beginner to lifer ray, i... Rizan imam August 8, 2010 8:33 PM
Hi I set all configuration required to add a... sawsan kasaab November 25, 2010 12:26 PM
Hey I tried to create a new portlet and I got, ... Smilelws2010 lwz December 16, 2010 5:18 AM
Hey Jay, I am also facing the same problem but... Amit Doshi December 29, 2010 1:39 AM
Hey, make sure your ... Yang Yu March 21, 2011 7:28 PM
Thanks yang, changing "\" with "/" did the... demonz elevenb February 22, 2012 2:30 PM
Very helpful, thanks. alexey -bykov November 9, 2012 8:16 AM

Hi This is very useful page to develop portal plugin. But While creating this plugin im getting following error. and building is getting failed.

===========================================


D:\JavaProgramFiles\Portals\Li­feray\SDK2\portlets>cd Liferay/SDK2/portlets
The system cannot find the path specified.

D:\JavaProgramFiles\Portals\Liferay\SDK2\portlets>ant deploy
Buildfile: build.xml

deploy:

loop-modules:

deploy-module:

BUILD FAILED
D:\JavaProgramFiles\Portals\Liferay\SDK2\build-common-plugins.xml:47: The following error occurred while executing this line:
D:\JavaProgramFiles\Portals\Liferay\SDK2\build-common-plugins.xml:79: The following error occurred while executing this line:
D:\JavaProgramFiles\Portals\Liferay\SDK2\build-common-plugins.xml:90: The following error occurred while executing this line:
D:\JavaProgramFiles\Portals\Liferay\SDK2\build-common-plugins.xml:53: The following error occurred while executing this line:
java.io.FileNotFoundException: D:\JavaProgramFiles\Portals\Liferay\SDK2\portlets\Pa-portlet\build.xml (The system cannot find the file specified)

Total time: 1 second
D:\JavaProgramFiles\Portals\Liferay\SDK2\portlets>
============
Please let me know what to do with this.

thanks
raghu
Posted on 10/20/08 2:28 PM.
I am also receiving this error when attempting to deploy. It looks like the build.xml file (and possible others) are missing from the template zip file. Has this release of the SDK been tested by anyone else?
Posted on 10/21/08 11:23 AM in reply to Raghu N N.
Same problem. Obviously buildfile is lacking. Creating a buildfile in the portletpath doesn't improve the situation either.
However isn't there any older version of the SDK which was working as described?
Posted on 10/24/08 1:44 AM in reply to matt baker.
I get the same error message. Is there a way to fix this?
Posted on 10/24/08 6:05 AM in reply to Stefan Kiefer.
OK, there is a good hint in the Forum with a complete Zip for creating the Portlet Stubs:

http://www.liferay.com/web/guest/community/forums/-/message_boards/message­/1474899#_19_message_1475260

with that zip everything works

thanks Samuel!
Posted on 10/24/08 6:51 AM in reply to Stefan Kiefer.
The portlet.zip file in question fixes the problem. I added the file as an attachment to this wiki page.
Posted on 10/29/08 6:11 AM in reply to Stefan Kiefer.
What about Clients, Hooks and Webs plugin?

Thank you for any help, expecially for Webs plugins!

Ivano Carrara
Posted on 11/5/08 2:32 AM in reply to Randy Brandenburg.
Idem problem is for th theme.zip file at $PLUGINS_SDK/themes, but this time miss liferay-look-and-feel.xml at docrootWEB-INF and for the you can not see the theme you created and added as plugin so use it after installation . I added the file(theme.zip ) as an attachment to this wiki page.
Posted on 11/14/08 1:16 AM in reply to Randy Brandenburg.
Idem problem is for the theme.zip file at $PLUGINS_SDK/themes, but this time miss liferay-look-and-feel.xml at docrootWEB-INF so , you can not see the theme you created and added as plugin , also you can't use it after installation . I added the file(theme.zip ) as an attachment to this wiki page.
Posted on 11/16/08 8:05 AM in reply to Alban KOM..
SDK vs EXT.
Not to start a huge debate or anything, but I would like to know when a developer might choose EXT over SDK or vice versa. My general inclination is that EXT is still needed when the core functionality of Liferay is needing extension and that the SDK is for day to day content creation and style modification. Is this a correct assumption.
I also have a question. I have EXT working and deploying projects, but I could not see in the ant properties files where it places files for the liferay server to deploy. Where would a logical place be to assign the auto.deploy.dir setting if one wanted the server to pick up the changes and deploy them? If auto.deploy.dir=${user.home}/liferay/deploy where would you configure the Liferay server to pick up these deployments?
Posted on 12/26/08 5:55 AM.
I'm trying using Suse linux but the command create.sh give me this error:

BUILD FAILED
Target "create" does not exist in the project "plugins".


Any help?
Thanks
Posted on 3/25/09 9:58 AM in reply to John Joseph Ryan.
Okay I just want to check the values here. I have Liferay installed on my local machine.
Where do I find ${user.name}? Is that the Computer name under My Computer in Windows? Or are you talking about a user in Liferay?
Similarly, where or what is ${user.home}? Would that be Domain under My Computer in Windows?
Lastly, is my.dir the directory where I have installed Liferay? eg. C:/Liferay

??Thanks!
Posted on 5/10/09 3:35 PM.
I was getting the build failed message like a few people have been receiving.

My issue was that I was using an incorrect user.name

Here is how to get the correct user.name

From command prompt in Windows (start > run > cmd):
echo %username%

The value coming back is the username you insert into your build.${user.name}.properties file

eg build.beau.properties
Posted on 6/26/09 6:24 AM in reply to Hoppy Patterson.
Hi,
please did you solve the problem
i have the same one
please help
thx
Posted on 7/7/09 8:58 AM in reply to Raghu N N.
Hi All,
Has anyone try to add a custom code to a portlet? it does not work.
I don't seem to see where or what I'm doing wrong.
I need help!

Here is the code:

#portlet-wrapper-56_INSTANCE_3qG3{

body {font-size:76%; font-family:"trebuchet MS", verdana, arial, sans-serif; backgroundemoticonf0f0f0;}

#minMax {min-width:700px; max-width:1100px; margin:0 auto; backgroundemoticone0e0e0;}

#header {backgroundemoticona31e39;}

#outer1 {float:left; width:20%; backgroundemoticond0c0c0;}
#outer2 {float:left; width:15%; backgroundemoticonc0c0c0;}
#outer3 {float:left; width:30%;}
#outer4 {float:right; width:15%; backgroundemoticond0d0d0;}
#outer5 {float:right; width:20%; backgroundemoticonc0b0b0;}
#outer1, #outer2, #outer3, #outer4, #outer5 {padding-bottom:32767px; margin-bottom:-32767px;}

#wrapper {overflow:hidden;}

#topbar {width:60%; float:left; backgroundemoticond8d8d8;}

#footer {clear:both; backgroundemoticon455c5a;}

h1 {font-size:20px; margin:0; padding:10px 0; coloremoticonfff;}
h3 {font-size:18px; margin:0; padding:8px 0;}
.content {padding:10px;}
p {font-size:12px; line-height:1.5em; margin:0; padding:5px 0;}
#footer p,
#header p {coloremoticonfff;}
#footer a {coloremoticonfff;}
#footer a:hover {text-decoration:none;}
}
Thanks
Patrick
Posted on 7/19/09 3:11 PM.
I have setup the Plugins SDK to override portal.properties settings.
Using method mentioned here http://wikis.sun.com/display/websynergy/Override+portal.properties+using+hooks+p­lugin

Build is successful, Hook is deploying successfully. BUT settings are not reflecting over.
I am trying to change following properties as:
terms.of.use.journal.article.id=11003
terms.of.use.journal.article.group.id=10­262

I checked thrugh Admin Frontend properties changed are reflected there but it's not working as it should be.
If I do same procedure with typical portal-ext way then it works.

What should be the problem?
Thanks in advance.
Posted on 7/27/09 2:00 AM.
I'm following the Jonas Yuan book, but unfortunately I cant use Subversion which is what he suggest to get the project into Eclipse

So I followed the steps mentioned here and I found that my plugins SDK project had 2 missing libs, Eclipse fixed the project importing 2 files:

portlet.jar from a Liferay Portal src and
portal-kernel.jar from an ext src, both of them i had as part of my workspace before

I don't now if that was what u meant with "Put all the jar files found in the /lib directory of the new plugin to the build path and export it"

thanks for the help
Posted on 9/2/09 2:39 PM.
What is the status of Maven ?
Posted on 6/23/10 1:19 AM in reply to Pablo M Mino.
PLEASE HELP ME OUT , I CANT UNDERSTANT THIS STEP CAN ONYONE ELOBARATE IT............
Preparation:
4. Install Apache Ant and make sure that ANT_HOME/bin is in your path to be able to build and package your work.
Posted on 7/23/10 9:50 AM.
Sudhakar you have to use the Ant build Tool.Download Ant 1.7 ,extract it ,set the classpath for building your application.
Posted on 7/26/10 3:29 AM in reply to Sudhakar T.
"ant war" does not create war file.
Posted on 8/8/10 8:46 AM.
'ant all' is not working in themes and portlets folders. Any piece of advice?
Posted on 8/8/10 9:35 AM.
Dear All,

I am new beginner to lifer ray, i downloaded and installed liferaysdk 6.0.2 and when i run the creat.bat file to creat a portlet it generates a folder structure in the same, But in which i can't able to find the src folder, So Please can any one tell me where i can write my action calss files.

Thanks
Posted on 8/8/10 8:33 PM.
I'm using Windows and have the same problem. For the life of me, I have no clue what folder it needs here. The offending line in our ant file "build.xml":

<target name="build" depends="retrieveVssChanges" >
<ant antfile="build.xml" dir="${basedir}/source" target="."/>
</target>

(My error is Target "." does not exist in the project "plugins".)


Any help?
Thanks
Posted on 11/18/10 7:46 AM in reply to Marco Guastalli.
Found the problem. In properties file (in our project named "build.properties") you have to refer to the tomcat folder inside the liferay folder. Since I was using the Liferay source distribution, this tomcat folder was not present. Changing to normal liferay distribution solved the problem.
Posted on 11/18/10 8:12 AM in reply to S F.
Hi
I set all configuration required to add a new portlet using plugins SDK,but when i run cmd and type the command:
create.bat my-greeting "My Greeting"
I get the next error:
"java.exe" is not recognized as an internal or external command,operable program or batch file
so,where is my error?
please,any help is welcome
Regards
Posted on 11/25/10 12:26 PM.
Hey
I tried to create a new portlet and I got,

C:\liferay-plugins-sdk-6.0.5\portlets>create.bat Greeting "Greetings"
Buildfile: C:\liferay-plugins-sdk-6.0.5\portlets\build.xml

create:
Expanding: C:\liferay-plugins-sdk-6.0.5\portlets\portlet.zip into C:
\liferay-plugins-sdk-6.0.5\portlets\Greeting-portlet
Created dir: C:\liferay-plugins-sdk-6.0.5\portlets\Greeting-portlet\
docroot\WEB-INF\tld

BUILD FAILED
C:\liferay-plugins-sdk-6.0.5\portlets\build.xml:40: C:\bundles\tomcat-6.0.26\web
apps\ROOT\WEB-INF\tld does not exist.

Total time: 1 second



Can anyone help please. Newbie here.
Posted on 12/16/10 5:18 AM in reply to sawsan kasaab.
Hey Jay,

I am also facing the same problem but the solution is check your

app.server.amit.doshi.properties in ext and also the

build.amit.doshi.properties in plugins there is given wrong path for the tomcat server that can cause this problem.. Try
it.. Let me know whether it works for you or not..

Thanks
Amit
Posted on 12/29/10 1:39 AM in reply to An Jay.
Hey, make sure your build.{$username}.properties some like "app.server.dir=D:/liferayFollowWeb/liferay-portal-6.0.5/tomcat-6.0.26
", especially use '/' instead of '\' in your path!
Good luck.
Posted on 3/21/11 7:28 PM in reply to An Jay.
Thanks yang,

changing "\" with "/" did the trick. it seems that the "\T" in a path like "C:\tomcat" is interpreted like a tabulation space.
Posted on 2/22/12 2:30 PM in reply to Yang Yu.
Very helpful, thanks.
Posted on 11/9/12 8:16 AM.