Creating a custom portlet

This recipe is very specific, because it shows how to generate a new portlet, install it on Liferay, and import it to the Eclipse IDE. Many recipes from this book assume that the user knows how to generate a new plugin, such as portlet, hook, or web. We will show you how to generate a new portlet using Apache Maven archetypes. The whole book assumes that you use Apache Maven to compile and deploy new portlets.

Getting ready

In order to correctly generate a new portlet, you need to have the following software stack:

• Java SDK 1.7 or later
• Apache Maven, we use 3.0.5 version
• Eclipse IDE (Kepler or later)

We also assume that you properly set the developer's environment, which was described in the previous recipe.

How to do it…

There are three phases to achieve our goal: generating a new portlet, compiling it, and deploying and importing it to the Eclipse IDE.

Generating a new portlet

The first thing we need to do is to create a Maven project. In order to generate it, follow these steps:

1. Go to the ${liferay.home}/workspace folder.
2. Execute mvn archetype:generate -Dfilter=liferay-portlet-archetype.
3. Choose a number for com.liferay.maven.archetypes:liferay-portlet-archetype. In our list, it is number 1:

   Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1

4. Choose the correct Liferay version. In our example, it will be 6.2.2, with the number 24.
5. Provide all the required Maven project information as follows:

   Define value for property 'groupId': : com.packtpub.portlet
   Define value for property 'artifactId': : first-portlet
   Define value for property 'version':  1.0-SNAPSHOT: : 
   Define value for property 'package':  com.packtpub.portlet: : 
   Confirm properties configuration:
   groupId: com.packtpub.portlet
   artifactId: first-portlet
   version: 1.0-SNAPSHOT
   package: com.packtpub.portlet
   Y: : y

6. In our workspace folder, a portlet called first-portlet should be generated.

Compiling the portlet and deploying it

With Apache Maven, it is easy to compile and deploy a portlet. Before invoking the Maven command, users have to set specific properties in the pom.xml file.

1. Go to the ${liferay.home}/workspace/first-portlet folder and edit the pom.xml file.
2. Under the <build> section, add the following properties definition:

   <properties>
     <liferay.version>6.2.2</liferay.version>
     <liferay.maven.plugin.version>6.2.2</liferay.maven.plugin.version>
     <liferay.auto.deploy.dir>${liferay.home}/deploy</liferay.auto.deploy.dir>
     <liferay.app.server.deploy.dir>${liferay.home}/tomcat-7.0.42/webapps</liferay.app.server.deploy.dir>
     <liferay.app.server.lib.global.dir>${liferay.home}/tomcat-7.0.42/lib/ext</liferay.app.server.lib.global.dir>
     <liferay.app.server.portal.dir>${liferay.home}/tomcat-7.0.42/webapps/ROOT</liferay.app.server.portal.dir>
   </properties>

   Tip

   Replace ${liferay.home} with the real path to your folders.

3. Save the pom.xml file.
4. Build a new project by executing the following command:

   mvn clean install
   

5. Make sure that your Apache Tomcat is running with Liferay.
6. Invoke the mvn liferay:deploy command and follow the catalina.out logfile. You should see a similar message:

   [PortletHotDeployListener:343] Registering portlets for first-portlet
   [PortletHotDeployListener:490] 1 portlet for first-portlet is available for use
   

Importing the portlet to the Eclipse IDE

After successfully generating sources by the Maven archetype plugin, the sources of our portlet can be imported to our Eclipse IDE. To import them, follow these steps:

1. Make sure that you are in the ${liferay.home}/workspace/first-portlet folder.
2. Run the mvn eclipse:clean eclipse:eclipse command.
3. Open your IDE and import first-portlet as a project by going to File | Import | General | Existing Projects into Workspace.

How it works…

A portlet project created from com.liferay.maven.archetypes:liferay-portlet-archetype has ready-to-use portlet implementation. In fact, it is very basic, but the entire folder's structure and configuration files are correctly created. Each portlet has four configuration files: portlet.xml, liferay-portlet.xml, liferay-display.xml, and liferay-plugin-package.properties. All of these files are placed in the first-portlet/src/main/webapp/WEB-INF folder.

The portlet.xml file is a portlet descriptor. It contains a portlet definition, such as name, portlet class, and so on.

The liferay-portlet.xml file is a kind of extension of portlet.xml. It is only understood by Liferay Portal. It gives additional information such as portlet's icon, path to the css and js files, and so on.

The liferay-display.xml file tells us in which section our portlet will be available. We will describe it later in the book.

The liferay-plugin-package.properties file is a metric of our portlet. This is a good place to specify version, tags, page URL, author, and license.

Detailed information on portlets is available in the JSR-168 and JSR-286 specification. There are many examples on how to use portlets, how to establish communication between portlets, or what is a portlet request lifecycle.

See also

For more information on portlets, refer to the following recipes:

• The Creating a role-dependent portlet recipe in Chapter 5, Roles and Permissions
• The Checking permissions in a custom portlet recipe in Chapter 5, Roles and Permissions
• The language properties hook recipe in Chapter 11, Quick Tricks and Advanced Knowledge
• The Using Liferay Service Bus for communication between portlets recipe in Chapter 11, Quick Tricks and Advanced Knowledge