Labels

ionic (40) Google Apps Script (28) Construct2 (6) Google API (5) Google Cloud (5) Java (5) presentation (5) jasper (4) plunker (4) Notepad++ (2) liferay (2) ms access (2) mysql (2) PHP (1) SQLite (1) android (1) blogspot (1) html5 (1) ionic-creator (1) javascript (1) mobile (1) plainjs (1) utilties (1)

Learn the powerful enterprise adaptable database:

Getting Started With ADABAS & Natural

Sunday, March 17, 2013

Liferay 6.1: Anatomy of a Portlet


This tutorial is based on  http://www.liferay.com/documentation/liferay-portal/6.1/development/-/ai/anatomy-of-a-portl-4 and it is assumed that your Liferay IDE is setup according to http://setup-steps.blogspot.com/2013/03/eclipse-liferay-ide-152-setting-up.html

A portlet project is made up at a minimum of three components:
  1. Java Source
  2. Configuration files
  3. 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:
  • PORTLET-NAME/
    • build.xml
    • docroot/
      • css/
      • js/
      • WEB-INF/
        • src/ (not created by default)
        • liferay-display.xml
        • liferay-plugin-package.properties
        • liferay-portlet.xml
        • portlet.xml
        • web.xml (not created by default)
      • icon.png
      • view.jsp
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. By default, MVCPortlet uses 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.
Here is a snapshot of files for a portlet plugin named my-greeting portlet as shown in Developer Studio’s Package Explorer. We will add and edit files in this directory to create a new and improved portlet!
02-portlet-development-3.png
Figure 3.4: Package Explorer of the My Greeting portlet
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 fileportlet.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. Described below are the Liferay-specific configuration files:
  • liferay-display.xml: This file describes what category the portlet should appear 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: 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 mention here. The DTD may be found in thedefinitions folder in the Liferay Portal source code.
  • liferay-plugin-package.properties: This file describes the plugin to Liferay’s hot deployer. Dependency JAR files (.jar) can be configured in this file. 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 .jar files from inside the .war file. That way you don’t have to include the .jars yourself and the .war will be lighter.
Client Side Files are the .jsp, .css, and JavaScript files that you write to implement your portlet’s user interface. These files should go in the docroot folder somewhere—either in the root of the folder or in a folder structure of their own. Remember that with portlets you are only dealing with a portion of the HTML document that is getting returned to the browser. Any HTML code you have in your client side files should be free of global tags such as <html> or <head>. Additionally, all CSS classes and element IDs must be name-spaced to prevent conflicts with other portlets. Liferay provides tools (a taglib and API methods) to generate the namespace that you should use.

A Closer Look at the My Greeting Portlet

If you are new to portlet development, this section will give you a better understanding of the configuration options of a portlet.
docroot/WEB-INF/portlet.xml
When using the Plugins SDK, the default content of the portlet descriptor is as follows (shown using Developer Studio’s Portlet Application Configuration Editor):
02-portlet-development-4.png
Figure 3.5: Portlet XML file of the My Greeting portlet
Here is a basic summary of what each of the elements represents:
portlet-name
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 to within Liferay Portal as the portlet id.
display-name
The display-name type contains a short name that is intended to be displayed by tools. It is used by display-nameelements. The display name need not be unique.
portlet-class
The portlet-class element contains the fully qualified name of the class that handles invocations to the portlet.
init-param
The init-param element contains a name/value pair as an initialization parameter of the portlet.
expiration-cache
Expiration-cache defines expiration-based caching for this portlet. The parameter indicates the time, in seconds, after which the portlet output expires. A value of -1 indicates that the output never expires.
supports
The supports element contains the supported mime-type. The element 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
Portlet-info defines portlet information.
security-role-ref
This 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, the Plugins SDK sets the contents of this descriptor, as shown in Developer Studio:
02-portlet-development-5.png
Figure 3.6: Liferay-Portlet XML file of the My Greeting portlet
Here is a basic summary of what some of the elements represents.
portlet-name
This element contains the canonical name of the portlet. This needs to be the same as the portlet-name specified in the portlet.xml file.
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 .css file for this portlet to include in the <head> tag of the page.
footer-portlet-javascript
The path to the .js file for this portlet, to be included at the end of the page before the </body> tag.
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 Portal source code for more information.
Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)