Building a Hello World portlet with Liferay

Today I tried to build a simple Hello World portlet with Liferay Portal. I am a little disappointed that the documentation isn’t as straight forward as I expected. I had to read through several documents and was confused by outdated/conflicting information. So, I am sharing my setup notes for people who might be interested to give it a try.

1. Download Liferay binary here. I downloaded the Tomcat bundle for ease of configuration. YMMV with other bundles.
2. Follow the quick installation here. I didn’t have any issue starting Tomcat with Liferay. It brings up the default portal page automatically. Do not close this page. We will revisit this page in a later step.
3. Download SDK from here. Look for a download link that starts with “Liferay Plugins SDK”.
4. If you don’t have Ant setup in your environment, follow the instructions in page 6 of the development documentation here. My environment is already setup with ant, so I just skipped this step.
5. Customize your own build.${username}.properties. I made copy of ${sdk_directory}/build.properties and created my own file in the same directory using the build.${username}.properties convention documented in page 7 of the development guide. Within this file, I updated app.server.dir property with the path to Tomcat’s directory in my local environment. The document has a typo about the other property: java.compiler. Reading the build.property file suggested to me that the property name should be javac.compiler. Since I only wanted the default configuration, which is modern, I didn’t change this second property.
6. Create a portlet using ant: I followed the instruction on page 8 in the development guide. It is very straight forward. Make sure you run the create command in the portlets directory in the sdk directory.

   cd ${sdk_directory}/portlets
   ant -Dportlet.name=hello -Dportlet.display.name="hello world title" create
   

7. After created the portlet, you should see a new directory that looks like hello-portlet. You can go into that directory and make changes to your liking. Since my goal was just to get a simple portlet running, I just added “Hello World” to hello-portlet/docroot/view.jsp file.
8. Deploy the portlet: Within the hello-portlet, I ran the following command to deploy the portlet:

   ant deploy
   

9. After I deployed the portlet, I did a quick check in the log file (catelina.out) to see if the portlet is available. I did notice that the message is slightly different from what development guide stated.
10. Add the portlet to the portal page: I returned to the default portal page on my browser. On the default portal page, there is a menu that has the label “welcome” on the to right corner. Liferay documentation called this “Dock”. If you mouse over this, you will see login option. To login, enter “bruno@7cogs.com” for email address and “bruno” for password. This information comes from the quick installation guide. All other documentation that I read all refers to “test@liferay.com” and “test”, which are wrong for the release that I downloaded. Once log-in, You can mouse over to the Dock and choose “Add Application”. Enter the name of your portlet in the search textfield, the list should automatically updated. If you can identify your portlet, click the “Add” link next to it. You should see the portlet showing on the portal page.

That should get your development setup for further portlet development. Have fun coding!

Update: If you want to use Glassfish, see Ari’s blog on this topic.