Anatomy of a Portlet
A portlet project is made up at a minimum of three components:
Client-side files (*.jsp, *.css, *.js, graphics, etc.)
When using Liferay's Plugins SDK these files are stored in a standard directory structure which looks like the following:
/src/ (not created by default)
The portlet we just created is a fully functional portlet which can be deployed to your Liferay instance.
New portlets are configured by default to use the MVCPortlet framework, a very light framework that hides part of the complexity of portlets and makes the most common operations easier. MVCPortlet uses separate JSPs for each page in the portlet.
Portlets created in the SDK are configured by default to use the MVCPortlet framework, a very light framework that hides part of the complexity of portlets and makes the most common operations easier. MVCPortlet uses separate JSPs for each page in the portlet. MVCPortlet uses by default a JSP with the mode name for each of the registered portlet modes. For example edit.jsp for the edit mode, help.jsp for the help mode, etc.
The Java Source is stored in the docroot/WEB-INF/src folder
The Configuration Files are stored in the docroot/WEB-INF folder. The standard JSR-286 portlet configuration file portlet.xml is here, as well as three Liferay-specific configuration files. The Liferay-specific configuration files are completely optional, but are important if your portlets are going to be deployed on a Liferay Portal server.
liferay-display.xml: This file describes what category the portlet should appear under in the Add menu in the dockbar (the horizontal bar that appear at the top of the page to all logged in users).
liferay-portlet.xml: This file describes some optional Liferay-specific enhancements for JSR-286 portlets that are installed on a Liferay Portal server. For example, you can set whether a portlet is instanceable, which means that you can place more than one portlet instance on a page, and each one will have its own separate data. Please see the DTD for this file for further details, as there are too many settings to list here. The DTD may be found in the definitions folder in the Liferay source code.
liferay-plugin-package.properties: This file describes the plugin to Liferay's hot deployer. One of the things that can be configured in this file is dependency .jars. If a portlet plugin has dependencies on particular .jar files that already come with Liferay, you can specify them in this file and the hot deployer will modify the .war file on deployment to copy those .jars inside. That way you don't have to include the .jars yourself and the .war will be lighter.
A Closer Look at the My Greeting Portlet
If you are new to portlet development, this section will take a closer look at the configuration options of a portlet.
When using the Plugins SDK, the default content of the portlet descriptor is as follows:
Here is a basic summary of what each of the elements represents:
The portlet-name element contains the canonical name of the portlet. Each portlet name is unique within the portlet application (that is, within the portlet plugin). This is also referred within Liferay Portal as the portlet id
The display-name type contains a short name that is intended to be displayed by tools. It is used by display-name elements. The display name need not be unique.
The portlet-class element contains the fully qualified class name that will handle invocations to the portlet.
The init-param element contains a name/value pair as an initialization param of the portlet.
Expiration-cache defines expiration-based caching for this portlet. The parameter indicates the time in seconds after which the portlet output expires. -1 indicates that the output never expires.
The supports element contains the supported mime-type. Supports also indicates the portlet modes a portlet supports for a specific content type. All portlets must support the view mode.
The concept of "portlet modes" is defined by the portlet specification. Modes are used to separate certain views of the portlet from others. What is special about portlet modes is that the portal knows about them and can provide generic ways to navigate between portlet modes (for example through links in the box surrounding the portlet when it is added to a page). For that reason they are useful for operations that are common to all or most portlets. The most common usage is to create an edit screen where each user can specify personal preferences for the portlet.
Portlet-info defines portlet information.
The security-role-ref element contains the declaration of a security role reference in the code of the web application. Specifically in Liferay, the role-name references which roles can access the portlet.
docroot/WEB-INF/liferay-portlet.xml - In addition to the standard portlet.xml options, there are optional Liferay-specific enhancements for Java Standard portlets that are installed on a Liferay Portal server. By default, Plugins SDK sets the contents of this descriptor to the following:
Here is a basic summary of what some of the elements represents.
The portlet-name element contains the canonical name of the portlet. This needs to be the same as the portlet-name given in portlet.xml
Path to icon image for this portlet
Indicates if multiple instances of this portlet can appear on the same page.
The path to the .css file for this portlet to be included in the <head> of the page
The path to the .js file for this portlet, to be included at the end of the page before </body>
There are many more elements that you should be aware of for more advanced development. Please see the DTD for this file in the definitions folder in the Liferay source code for more information.