Portlets can be created in a Plugins SDK project or a Liferay Maven project. Liferay IDE lets you create either project type using command line tools: Ant in the Plugins SDK or Maven Archetype in Maven.
In this tutorial, you’ll learn how to create MVC portlets in a Plugins SDK project, using Liferay IDE and Ant. To learn how to create Liferay Maven projects, see the tutorial Creating Liferay Maven plugins from IDE or the tutorial Creating Liferay Maven Plugins from the Command Line. If you’re completely new to Liferay, you may first want to go through the Beginning Liferay Development learning path.
First up is creating a portlet with Liferay IDE, so go ahead and get started.
Creating a Liferay MVC Portlet in Liferay IDE
Go to File → New → Liferay Plugin Project.
Fill in the Project name and Display name. Project names must have no spaces and it’s a best practice to specify them in lowercase. The Display name, however, can have spaces. You should specify the portlet’s Display name just as you want it displayed to the user.
Leave the Use default location checkbox checked. By default, the default location is set to your Plugins SDK. If you’d like to change where your plugin project is saved in your file system, uncheck the box and specify your alternate location.
Select the Ant (liferay-plugins-sdk) option for your build type.
Your configured SDK and Liferay Runtime should already be selected. If you haven’t yet pointed Liferay IDE to a Plugins SDK, click the Configure SDKs button to the right of the Plugins SDK dropdown menu to open the Installed Plugin SDKs management wizard. You can also access the New Server Runtime Environment wizard if you need to set up your runtime server; just click the New Liferay Runtime button next to the Liferay Portal Runtime dropdown menu.
Select Portlet as your plugin type. Alternatively, you can select Service Builder Portlet if you know you want to use Liferay’s service builder for your portlet.
If you want to launch the New Portlet Wizard after your project is created, select the checkbox of that name. The New Portlet Wizard guides you in creating a custom portlet class.
Click Next if you selected Portlet as your plugin type. If you selected Service Builder Portlet as your plugin type, then click Finish.
If you selected Portlet as your plugin type, make sure that the Liferay MVC framework is selected in the next window and click Finish.
With Liferay IDE, you can create a new plugin project or if you already have a project, create a new plugin in an existing project. A single Liferay project can contain multiple plugins. Next you’ll see how the same process is done using the terminal.
Creating a Liferay MVC Portlet Using the Terminal
Navigate to the
portlets directory in the terminal and enter the appropriate command for your operating system:
In Linux and Mac OS X, enter
./create.sh [project-name] ["Portlet Display Name"]
In Windows, enter
create.bat [project-name] ["Portlet Display Name"]
You should get a
BUILD SUCCESSFUL message from Ant, and there will now be a new folder inside of the
portlets folder in your Plugins SDK. This folder is your new portlet project. This is where you will be implementing your own functionality. Notice that the Plugins SDK automatically appends “-portlet” to the project name when creating this folder.
Alternatively, if you will not be using the Plugins SDK to house your portlet projects, you can copy your newly created portlet project into your IDE of choice and work with it there. If you do this, you will need to make sure the project references some
.jar files from your Liferay installation, or you may get compile errors. Since the Ant scripts in the Plugins SDK do this for you automatically, you don’t get these errors when working with the Plugins SDK.
To resolve the dependencies for portlet projects, see the classpath entries in the
build-common.xml file in the Plugins SDK project. You can determine from the
portal.classpath entries, which
.jar files are necessary to build your newly created portlet project. This is not a recommended configuration, and it is encouraged that you keep your projects in the Plugins SDK.
A portlet project is made up of at least three components:
Client-side files (
.js, graphics files, etc.).
When using Liferay’s Plugins SDK, these files are stored in a standard directory structure:
src/- this folder is not created by default.
By default, new portlets use the MVCPortlet framework, a light framework that hides part of the complexity of portlets and makes the most common operations easier. The default MVCPortlet project uses separate JSPs for each portlet mode: each of the registered portlet modes has a corresponding JSP with the same name as the mode. For example, ‘edit.jsp’ is for edit mode and ‘help.jsp’ is for help mode.
The Java Source is stored in the
The Configuration Files are stored in the
docroot/WEB-INF folder. Files stored here include the standard JSR-286 portlet configuration file
portlet.xml, as well as three optional Liferay-specific configuration files. The Liferay-specific configuration files, while optional, are important if your portlets will be deployed on a Liferay Portal server. Here’s a description of the Liferay-specific files:
liferay-display.xml- Describes the category the portlet appears under in the Add menu of the Dockbar (the horizontal bar that appears at the top of the page to all logged-in users).
liferay-plugin-package.properties- Describes the plugin to Liferay’s hot deployer. You can configure Portal Access Control List (PACL) properties,
.jardependencies, and more.
liferay-portlet.xml- Describes Liferay-specific enhancements for JSR-286 portlets installed on a Liferay Portal server. For example, you can set an image icon to represent the app, trigger a job for the scheduler, and much more. A complete listing of this file’s settings is in its DTD in the
definitionsfolder in the Liferay Portal source code.
Client Side Files are the
.js files that you write to implement your portlet’s user interface. These files should go in the
.jsp files can be placed in the root of the folder, while
.js files are given their own subfolders in
docroot. Remember, with portlets you’re only dealing with a portion of the HTML document that is getting returned to the browser. Any HTML code in your client side files must be free of global tags like
<head>. Additionally, namespace all CSS classes and element IDs to prevent conflicts with other portlets. Liferay provides two tools, a taglib and API methods, to generate a namespace for you. See the Using Portlet Namespacing tutorial to learn more about namespacing.
Congrats! Now you understand the basic structure of Liferay MVC portlets and you have two handy ways to create them in your bag O’trix!