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.
web.xml- this file is not created by default.
The portlet we just created is fully functional and deployable to your Liferay instance.
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-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.
liferay-plugin-package.properties- Describes the plugin to Liferay’s hot deployer. You can configure Portal Access Control List (PACL) properties,
.jardependencies, and more.
Client Side Files are the
.js files that you write to implement your portlet’s user interface. These files should go in the
docroot folder, either in the root of the folder or in a folder structure that makes sense for your application. 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.
A Closer Look at the My Greeting Portlet
If you’re new to portlet development, this section will enhance your understanding of portlet configuration options.
In the Plugins SDK, the portlet descriptor’s default content looks like this (shown using Developer Studio’s Portlet Application Configuration Editor):
Here’s a basic summary of what each element represents:
portlet-name: Contains the portlet’s canonical name. Each portlet name is unique within the portlet application (that is, within the portlet plugin). In Liferay Portal, this is also referred to as the portlet ID.
display-name: Contains a short name that’s shown by the portal whenever this application needs to be identified. It’s used by
display-nameelements. The display name need not be unique.
portlet-class: Contains the fully qualified name of the class that handles invocations to the portlet.
init-param: Contains a name/value pair as an initialization parameter of the portlet.
expiration-cache: Indicates the time, in seconds, after which the portlet output expires. A value of
-1indicates that the output never expires.
supports: Contains the supported mime-type, and indicates the portlet modes supported for a specific content type. The concept of “portlet modes” is defined by the portlet specification. Modes are used to separate certain views of the portlet from others. The portal is aware of the portlet modes and provides generic ways to navigate between them (for example, using links in the box surrounding the portlet when it’s added to a page), so they’re 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. All portlets must support the view mode.
portlet-info: Defines information that can be used for the portlet title-bar and for the portal’s categorization of the portlet. The JSR-286 specification defines a few resource elements that can be used for these purposes:
keywords. You can either include resource elements directly in a
portlet-infoelement or you can place them in resource bundles.
Specifying the information directly into the
portlet-infoelement in your
portlet.xmlfile is straightforward. For example, to you could specify a weather portlet’s information, like this:
<portlet> ... <portlet-info> <title>Weather Portlet</title> <short-title>Weather></short-title> <keywords>weather,forecast</keywords> </portlet-info> ... </portlet>
Alternatively, you can specify this same information as resources in a resource bundle file for your portlet. For example, you could create file
docroot/WEB-INF/src/content/Language.properties, in your portlet project, to specify your portlet’s title, short title, and keywords:
# Default Resource Bundle # # filename: Language.properties # Portlet Info resource bundle example javax.portlet.title=Weather Portlet javax.portlet.short-title=Weather javax.portlet.keywords=weather,forecast
To use the resource bundle, you’d reference it in your
portlet.xmlfile, in your
portletelement just before your
<portlet> ... <resource-bundle>content.Language</resource-bundle> <portlet-info>...</portlet-info> ... </portlet>
As a best practice, if you’re not planning on supporting localized title, short title, and keywords values for your portlet, simply specify them within the
<portlet-info>element in your
portlet.xmlfile. Otherwise, if you’re ready to provide localized values, use a resource bundle for specifying your default values and specify the localized values in separate resource bundles.
Specifying localized values for your portlet’s title, short title, and keywords in resource bundles is easy. For example, if you’re supporting German and English locales, you’d create
Language_en.propertiesfiles, respectively, in your portlet’s
docroot/WEB-INF/src/content/directory. This is the same directory as your default resource bundle file
Language.properties. The contents of the German and English resource bundles may look like the following:
# English Resource Bundle # # filename: Language_en.properties # Portlet Info resource bundle example javax.portlet.title=Weather Portlet javax.portlet.short-title=Weather javax.portlet.keywords=weather,forecast # German Resource Bundle # # filename: Language_de.properties # Portlet Info resource bundle example javax.portlet.title=Wetter Portlet javax.portlet.short-title=Wetter javax.portlet.keywords=wetter,vorhersage
You’d reference your default bundle and these localized bundles in your
portlet.xmlfile, like this:
<portlet> ... <resource-bundle>content.Language</resource-bundle> <resource-bundle>content.Language_de</resource-bundle> <resource-bundle>content.Language_en</resource-bundle> <portlet-info>...</portlet-info> ... </portlet>
If you’re mavenizing your portlet, make sure to copy your
contentfolder into your portlet’s
For more information, see the JSR-286 portlet specification, at http://www.jcp.org/en/jsr/detail?id=286.
security-role-ref: Contains the declaration of a security role reference in the code of the web application. Specifically in Liferay, the
role-namereferences 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, the Plugins SDK sets the contents of this descriptor, as shown in Developer Studio:
Here’s a basic summary of what some of the elements represent.
portlet-name: Contains the canonical name of the portlet. This needs to be the same as the
portlet-namespecified in the
icon: Path to icon image for this portlet.
instanceable: Indicates whether multiple instances of this portlet can appear on the same page.
header-portlet-css: The path to the
.cssfile for this portlet to include in the
<head>tag of the page.
.jsfile for this portlet, to be included at the end of the page before the
There are many more elements that you should be aware of for more advanced development. They’re all listed in the DTD for this file, which is found in the
definitions folder in the Liferay Portal source code.