First Portlet

Creating a Portlet

Creating portlets with the Plugins SDK is extremely simple. As noted before, there is a portlets folder inside of the Plugins SDK folder. This is where your portlet projects will reside. To create a new portlet, first decide what its name is going to be. You need both a project name (without spaces) and a display name (which can have spaces). When you have decided on your portlet's name, you are ready to create the project. For the greeting portlet, the project name is "my-greeting", and the portlet title is "My Greeting". Navigate to the portlets directory in the terminal and enter the following command (Linux and Mac OS X):

./create.sh my-greeting "My Greeting"

On Windows enter the following instead:

create.bat my-greeting "My Greeting"

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 may 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 class path entries in the build-common.xml file in the Plugins SDK project. You will be able to determine from the plugin.classpath and portal.classpath entries which .jar files are necessary to build your newly created portlet project.

Tip: If you are using a source control system such as Subversion, CVS, Mercurial, Git, etc. this might 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.

Deploying the Portlet

Liferay provides a mechanism called autodeploy that makes deploying portlets (and any other plugin type) a breeze. All you need to do is drop a WAR file into a directory and the portal will take care of making any necessary changes specific to Liferay and then deploy it to the application server. This will be the method used throughout this guide.

Tip: Liferay supports a wide variety of application servers. Many of them, such as Tomcat or Jboss, provide a simple way to deploy web applications by just copying a file into a folder and Liferay's autodeploy mechanism makes use of that possibility. You should be aware though that some application servers, such as Websphere or Weblogic require the use of specific tools to deploy web applications, so Liferay's autodeploy process won't work for them.

Open a terminal window in your portlets/my-greeting-portlet directory and enter this command:

ant deploy

You should get a BUILD SUCCESSFUL message, which means that your portlet is now being deployed. If you switch to the terminal window running Liferay, and wait for a few seconds, you should see the message "1 portlet for my-greeting-portlet is available for use". If not, something is wrong and you should double-check your configuration.

Go to your web browser and log in to the portal as explained earlier. Then hover over Add at the top of the page, and click on More. Select the Sample category, and then click Add next to My Greeting. Your portlet should appear in the page below. Congratulations, you've just created your first portlet!