資料　リソース

Liferayは、コミュニティにてテクノロジーをより良く使うために役立つ豊富なリソースと知識を提供しています。

Liferay Portal 6.1 - Development Guide

目録 »
Portlet Development »
Anatomy of a Portlet

Anatomy of a Portlet

A portlet project is made up of at least three components:

  1. Java Source.

  2. Configuration files.

  3. Client-side files (.jsp, .css, .js, graphics files, etc.).

When using Liferay’s Plugins SDK, these files are stored in a standard directory structure:

  • PORTLET-NAME/

    • build.xml
    • docroot/
    - `css/`

- `js/`

- `WEB-INF/`

    - `src/` - this folder is not created by default.

    - `liferay-display.xml`

    - `liferay-plugin-package.properties`

    - `liferay-portlet.xml`

    - `portlet.xml`

    - `web.xml` - this file is not created by default.

- `icon.png`

- `view.jsp`

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 docroot/WEB-INF/src folder.

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 definitions folder 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, .jar dependencies, and more.

Client Side Files are the .jsp, .css, and .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 <html> or <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.

docroot/WEB-INF/portlet.xml

In the Plugins SDK, the portlet descriptor’s default content looks like this (shown using Developer Studio’s Portlet Application Configuration Editor):

02-portlet-development-4.png

Figure 3.3: Portlet XML file of the My Greeting portlet

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-name elements. 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 -1 indicates 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 portlet information.

  • security-role-ref: Security-role-ref 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.4: Liferay-Portlet XML file of the My Greeting portlet

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-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. They’re all listed in the DTD for this file, which is found in the definitions folder in the Liferay Portal source code.

目録 »
Portlet Development »
Anatomy of a Portlet