Leveraging the Plugins SDK
Java developers use a wide variety of tools and development environments. Liferay makes every effort to remain tool agnostic, so you can choose the tools that work best for you. If you don’t want to use Liferay IDE, you can use Liferay’s Plugins Software Development Kit (SDK) all by itself. The Plugins SDK is based on Apache Ant, and can be used along with any editor or Integrated Development Environment (IDE).
In this section, we’ll explain how to set up a Plugins SDK. We’ll also discuss its file structure and available Ant targets and share some best practices to help you get the most out of the Plugins SDK.
Setting up the Plugins SDK is easy. Let’s get to it.
Installing the SDK
The first thing you should do is install Liferay Portal. If you haven’t already installed a Liferay bundle, follow the instructions in the Installation and Setup chapter of Using Liferay Portal. Many people use the Tomcat bundle for development, as it’s small, fast, and takes up fewer resources than most other servlet containers. Although you can use any application server supported by Liferay Portal for development, our examples use the Tomcat bundle.
Note: In Liferay Developer Studio, the SDK is already installed and ready to use. Liferay Portal Enterprise Edition (EE) comes with Liferay Developer Studio and much more (see CE vs EE). Download a free trial of Liferay Portal EE today.
Download The Plugins SDK from our web site at http://www.liferay.com.
Click the Downloads link at the top of the page.
From the Liferay Portal 6.2 Community Edition section, select the Plugins SDK option.
Unzip the archive to a folder of your choosing. Because some operating systems have trouble running Java applications from folders with names containing spaces, avoid using spaces when naming your folder.
On Windows, to build a plugin’s services (see Chapter 4 on Service Builder), the Plugins SDK and Liferay Portal instance must be on the same drive. E.g., if your Liferay Portal instance is on your
C:\ drive, your Plugins SDK must also be on your
C:\ drive in order for Service Builder to be able to run successfully.
Tip: By default, Liferay Portal Community Edition comes bundled with many plugins. It’s common to remove them to speed up the server start-up. Just navigate to the
liferay-portal-[version]/tomcat-[tomcat-version]/webapps directory and delete all its subdirectories except for
Now that you’ve installed the Plugins SDK, let’s configure Apache Ant for use in developing your plugins.
Building projects in the Plugins SDK requires that you install Ant (version 1.7 or higher) on your machine. Download the latest version of Ant from http://ant.apache.org/. Extract the archive’s contents into a folder of your choosing.
Now that Ant is installed, create an
ANT_HOME environment variable to capture your Ant installation location. Then put Ant’s
bin directory (e.g.,
$ANT_HOME/bin) in your path. We’ll give you examples of doing this on Linux (Unix or Mac OS X) and Windows.
On Unix-like systems (Linux or Mac OS X), if your Ant installation directory is
/java/apache-ant-<version> and your shell is Bash, set
ANT_HOME and adjust your path by specifying the following in
.bash_profile or from your terminal:
On Windows, if your Ant installation folder is
C:\Java\apache-ant-<version>, set your
ANT_HOME and path environment variables appropriately in your system properties:
Select Start, then right-select Computer → Properties.
In the Advanced tab, click Environment Variables….
In the System variables section, click New….
Variable value: (e.g.,
Also in the System variables section, select your path variable and click Edit….
%JAVA_HOME%\bin; and click OK.
Click OK to close all system property windows.
Open a new command prompt for your new environment variables to take affect.
To verify Ant is in your path, execute
ant -version from your terminal to make sure your output looks similar to this:
Apache Ant(TM) version <version> compiled on <date>
If the version information doesn’t display, make sure your Ant installation is referenced in your path.
Now that Ant is configured, let’s set up your Plugins SDK environment.
Plugins SDK Configuration
Now we have the proper tools set up. Next, we need to configure our Plugins SDK. It needs to know the location of our Liferay installation so it can compile plugins against Liferay’s JAR files and can deploy plugins to your Liferay instance. The Plugins SDK contains a
build.properties file that contains the default settings about the location of your Liferay installation and your deployment folder. You can use this file as a reference, but you shouldn’t modify it directly (In fact, you will see the message “DO NOT EDIT THIS FILE” at the top if you open it). In order to override the default settings, create a new file named
build.[username].properties in the same folder, where
[username] is your user ID on your machine. For example, if your user name is jbloggs, your file name would be
Edit this file and add the following lines:
app.server.type=[the name build.properties uses for your application server type]
app.server.parent.dir=[the directory containing your Liferay bundle]
app.server.tomcat.dir=[the directory containing your application server]
If you are using Liferay Portal bundled with Tomcat 7.0.42 and your bundle is in your
C:/liferay-portal-6.2 folder, you’d specify the following lines:
Since we’re using the Tomcat application server, we specified
tomcat as our app server type and we specified the
app.server.tomcat.dir property. See the Plugins SDK’s
build.properties for the name of the app server property that matches your app server.
Save the file. Next, let’s consider the structure of the Plugins SDK.
Structure of the SDK
Each folder in the Plugins SDK contains 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/ - archived plugins for distribution and deployment.
ext/ - Ext plugins directory. See Chapter 13 on Ext plugins.
hooks/ - hook plugins directory. See Chapter 10 on hooks.
layouttpl/ - layout templates directory. See Chapter 9 on creating Liferay Themes and Layout Templates.
lib/ - commonly referenced libraries.
misc/ - development configuration files. Example, a source code formatting specification file.
portlets/ - portlet plugins directory. See Chapter 3 on portlet development.
themes/ - themes plugins directory. See Chapter 9 on creating Liferay themes.
tools/ - plugin templates and utilities.
webs/ - web plugins directory.
build.properties - default SDK properties.
build.<username>.properties - (optional) override SDK properties.
build.xml - contains targets to invoke in the SDK.
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.
New plugins are placed in their own subdirectory of the appropriate plugin type. For instance, a new portlet called greeting-portlet would reside in
There’s an Ant build file called
build.xml in each of the plugins directories. Here are some Ant targets you’ll commonly use in developing your plugins:
build-service - builds the service layer for a plugin, using Liferay Service Builder.
clean - cleans the residual files created by the invocations of the compilation, archiving, and deployment targets.
compile - compiles the plugin source code.
deploy - builds and deploys the plugin to your application server.
format-source - formats the source code per Liferay’s source code guidelines, informing you of violations that must be addressed. See the Development Sytle community wiki page for details.
format-javadoc - formats the Javadoc per Liferay’s Javadoc guidelines. See the Javadoc Guidelines community wiki page for details.
Next, let’s create a plugin using Liferay SDK from a terminal environment.
Creating Plugins with Liferay SDK
You saw how easy it is to create and deploy Liferay plugin projects using Liferay IDE with an installed Liferay SDK. If you don’t want to use Eclipse, you can still leverage the SDK to create your Liferay plugins.
Let’s pretend that Harold Schnozz, Nose-ster’s founder, despises Eclipse. We may not agree with his objections, but since he’s paying us good money to create portlets for his organization, we’ll make do without the benefit of Liferay IDE.
Navigate to the
portlets folder of your Plugins SDK and follow these steps:
On Linux and Mac OS X, enter
./create.sh event-listing "Event Listing"
On Windows, enter
create.bat event-listing "Event Listing"
Your terminal will display a BUILD SUCCESSFUL message from Ant, and a new folder with your portlet plugin’s directory structure will be created inside of the
portlets folder in your Plugins SDK. This is where you’ll work to implement your own functionality. Notice that the Plugins SDK automatically appends “-portlet” to the project name when creating its directory.
Figure 2.17: Creating the Event Listing Portlet.
Tip: If you are using a source control system such as Subversion, CVS, Mercurial, Git, etc., this would be a good moment to do an initial check-in of your changes. After building the plugin for deployment, several additional files will be generated that should not be handled by the source control system.
Now you have a Liferay portlet project for our Event Listing portlet. We still need to deploy the project to our Liferay Server. With Liferay IDE you had multiple options: drag and drop your project onto the server, or right click the server and select Add and Remove…. It’s almost as easy using an ant target. Simply open a terminal window in your
portlets/event-listing-portlet directory and enter
A BUILD SUCCESSFUL message indicates your portlet is now being deployed. If you switch to the terminal window running Liferay, within a few seconds you should see the message
1 portlet for my-greeting-portlet is available for use. If not, double-check your configuration.
In your web browser, log in to the portal as explained earlier. Hover over Add at the top of the page and click on More. Select the Sample category, and then click Add next to Event Listing. Your portlet appears in the page below.
Next, let’s consider some best practices for developing plugins using the SDK.
The Plugins SDK can house all of your plugin projects enterprise-wide, or you can have separate Plugins SDK projects for each plugin. For example, if you have an internal Intranet using Liferay with some custom portlets, you can keep those portlets and themes in their own Plugins SDK project in your source code projects. Or, you can further separate your projects by having a different Plugins SDK project for each portlet or theme project.
It’s also possible to use the Plugins SDK as a simple cross-platform project generator. Create a plugin project using the Plugins SDK and then copy the resulting project folder to your IDE of choice. You’ll have to manually modify the Ant scripts, but this process makes it possible to create plugins with the Plugins SDK while conforming to the strict standards some organizations have for their Java projects.
Now you know of two Liferay-specific tools that streamline development in Liferay. But both use the Apache Ant build tool. If that’s a deal breaker for you, consider using Liferay’s Apache Maven archetypes to build your custom Liferay plugins. We’ll look at Maven next, and we’ll have some fun with classic poetry while doing it.