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" 

./create.sh newtheme "My New Theme"

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

 ./create.sh newportlet "My New Portlet" 

• 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