|
|
|
|
|
|
Developing Portlets
An integral part of any portal solution is the portlet application. This chapter explains what you need to know to create a portlet application.
This topic includes the following sections:
Introduction
Generally, a main portal page is organized into smaller display areas. Using the WebLogic Personalization Server, the portal developer can create a main page layout, with flexible methods for determining custom headers, footers, look and feel elements, and the primary content areas.
The most information-rich part of the main page consists of a set of portlets, laid out in columns. Each portlet is a small content area, provided to display a particular type of information. These portlets are developed especially for each portal and are written in JSP, so there is great flexibility in what can be displayed. There is a standard set of development guidelines, coupled with portal services, to ensure portal and portlets are well-behaved.
The primary way dynamic functionality of the personalization components is made available to portlets is via custom JSP tags resident in tag libraries. These tags hide much of the internal runtime complexity of the Personalization Server, presenting a small, well-defined interface to its functions. Portlets may also access certain types of personalization EJBs directly, using embedded Java to access Personalization Server functionality.
Each portlet may have a series of custom pages with specific functions associated with it, accessed via button clicks on the portlet. An edit page may make available to the user HTML input elements, in which the user can enter data on preferences specific to that portlet. A full page (or pages) version may be brought up to show an arbitrary amount of detail. A help page can be set up. The portlet may also be maximized, minimized, or floated in its own window.
What is a portlet?
From the end-user point-of-view, a portlet is a specialized content area that occupies a small "window" in the portal page. For example, a portlet can contain travel itineraries, business news, local weather, or sports scores. The user can personalize the content, appearance, and position of the portlet according to the profile preferences set by the administrator and group to which the user belongs. The user can also edit, maximize, minimize, or float the portlet window.
The following figure shows how portlets appear in a portal home page:
Figure 4-1 Portlet Homepage View
From a server application point-of-view, a portlet is a content component implemented as a JSP that defines the static and dynamic content for a specific content subject (weather, business news, etc.) in the portal page. The portlet JSP generates dynamic HTML content from the server by accessing data entities or content adapters implemented using the J2EE platform. The Portlet JSP then displays the content in the portal. Note: All of the portlets in a portal are included in a single HTML page, through the use of the <jsp:include> action. Figure 4-2 Portal Application Programming Model
Creating a portlet application
To create a portlet application, you should be a J2EE developer with a background in JavaServer PagesTM (JSP), JavaScript and HTML, and have a knowledge of Enterprise Java Beans.
The portlet application is a JSP that contains code responsible for retrieving personalized content and rendering it as HTML.
Once you have created your portlets, you can associate them with one or more portals. Therefore, you must create your portlet applications before using the Portal Administration Tool to create and define your portal.
Defining the Portlet JSP
The portal treats portlets as components or HTML fragments, not as entire HTML documents. The portal relies on the portlet application to create an HTML fragment for its portlet content. The portal renders the portlet's content in the portal page according to the personalization rules (the row and column position, colors, etc.) for the portal, group, and user levels.
When creating a portlet application, keep the following items in mind to ensure that your portlets run efficiently:
To define your portlet JSP:
Note: You do not need to create a JSP for the portlet title bar because it is included in the WebLogic Personalization Server. (public.html/portals/repository/titlebar.jsp). The portlet title bar displays the appropriate portlet titlebar icons and the name of the portlet you defined in the Portal Administration Tool.
Note: Avoid using the following HTML tags in your portlet content page. The HTML generated by the portlet content page is an HTML fragment contained in a larger portal HTML page, not a separate HTML document.
Working Within the Portal Framework
The portal framework consists of JavaServer Pages, JSP tag libraries, EJBs, Java servlets, and other supporting Java objects. The main Java servlet is the Flow Manager. The Flow Manager receives all incoming HTTP requests and dispatches each request to the appropriate destination URL. As a result, all access to your portal pages is controlled by the Flow Manager. The following diagram shows where the Flow Manager fits in the portal framework.
Figure 4-3 Portal Framework
Extending the PortalJspBase Class It is recommended that your portlet JSP extend the framework's PortalJspBase Java class. This class contains many convenience methods which perform general tasks for your portlet JSP page, such as accessing session information, the traffic uri, and user login information. To extend the PortalJspBase class, include the following code at the top of your portlet JSP:<%@ page extends="com.beasys.commerce.portal.admin.PortalJspBase"%>
Accessing Portal Session Information
The portal session information you can access from the PortalJspBase class are listed in the following table which lists the name, type, and description for each session value. For more information, see the Portal API Documentation.
You can set the portal session's SERVICEMANAGER_USER and SERVICEMANAGER_SUCCESSOR through the following JspBase methods:
Sending Requests Through the Flow Manager
Remember that all HTTP requests and responses are sent to the Flow Manager servlet. Therefore, your portlet HTML must refer to the Flow Manager's URL for URL links and HTML form processing.
Using URL Links in Your Portlet
If your portlet contains links to a JSP page that is not a portlet, use the following PortalJspBase method to create your URL and to guarantee that the HTTP request is sent to the service manager URL:
public String createURL(HttpServletRequest aRequest, String destination, String parameters)
The destination should be a relative or qualified file location in the form such as example/mytodo.jsp, or /yourportal/example/mytodo.jsp. The path is relative to the documentRoot, as specified in weblogic.properties. Parameters should be a string such as column=4&row=5.
Note: Parameter values should already be encoded as you would for any HTTP request. Example: String parms = "column=" + java.net.URLEncoder.encode("4");
Because of the way the JSP engine handles jsp:forward and jsp:include, you must fixup the relative URLs in your portlet, especially relative links to images. The web browser thinks the root for relative links is the directory in which the Flow Manager resides and not your portlet's directory.
To fixup relative URLs use the following ToolsJspBase method:
public static String ToolsJspBase fixupRelativeURL(String aURL, HttpServletRequest aRequest)
where aURL is the destination URL to fix up and aRequest is the current HTTP request. In your JSP page, use the following method to code a 'fixup':
<img src="<%=fixupRelativeURL("images/quote.gif", request)%>"width="50" height="35" border="0">Note: For the repository feature to work with jsp:include and jsp:forward, use reconcile file to determine the correct location of the file that is included or forwarded.
Example: <jsp:forward page="<%=reconcileFile(request, "login.jsp")%>" />
HTML Form Processing
If your portlet contains an HTML form, send all requests to the Flow Manager and set the destination request parameter.
To process HTML forms:
public String getTrafficURI(HttpServletRequest aRequest)
The following example shows the use of the HTML form action to send a form request to the Flow Manager:
<form method="post" action="<%=getTrafficURI(request)%>">
To set the request destination for HTML forms, enter the following code within your form in your JSP page:
<input type="hidden" name="<%=DESTINATION_TAG%>" value="example/mytodo.jsp">
Note: Do not go through the Flow Manager for HTTP requests to other servers.
Retrieving the Home Page
The Flow Manager sets the home page for each portal in the Portal Framework session information. The home page is registered as an initial argument for Flow Manager servlet in weblogic.properties. Use the following PortalJspBase method call to retrieve the home page:
public String getHomePage(HttpServletRequest aRequest)
Retrieving the Current Page
You can also retrieve the current page from the Portal Framework session information by using the following PortalJspBase method:
public String getCurrentPage(HttpServletRequest aRequest)
Note: When you maximize a portlet, the current page changes to fullscreenportlet.jsp.
Setting the Request Destination
When routing a request through the Flow Manager, you must specify the destination that should receive the request. The destination can be relative to the current page (portal.jsp, full-screen portlet.jsp, etc.) or a fully qualified path from the document root.
Note: The DESTINATION_TAG constant is available in PortalJspBase.
If your portlet contains links to other portal pages, use the following PortalJspBase method to create your URL and to guarantee that the HTTP request is sent to the service manager URL:
public String createURL(HttpServletRequest aRequest, String destination, String parameters)
The destination should be a relative or qualified file location in the form such as example/mytodo.jsp, or /yourportal/example/mytodo.jsp.
In some cases, you may need to override the request parameter used by the Flow Manager. For example, use an override destination if your page contains a form that needs to be validated and forwarded elsewhere after validation. Use the following PortalJspBase method in your JSP page:
public void setOverrideDestination(HttpServletRequest req, String dest)
To set the request destination for HTML forms, enter the following code within your form in your JSP page:
<input type="hidden" name="<%=DESTINATION_TAG%>" value="example/mytodo.jsp">
Tracking User Login Status
You can log the user in or out and track whether a user is currently logged in.
Use the following PortalJspBase method to track the user login status of a portal session:
public void setLoggedIn(HttpServletRequest aRequest, HttpServletResponse aResponse, boolean aBool)
public Boolean getLoggedIn(HttpServletRequest aRequest)
Loading Content from an External URL
According to the JSP specification, a JSP processed by a JSP engine must be relative to the server in which the JSP engine is running, requiring that all of your portlets reside in your portal server and not on an external web site. However, you can use the uricontent tag to download the contents of an external URL into your portlet. If you download the contents of a URL into your portlet, you need to fully qualify the images located on the remote server because the relative links contained within the remote URL will not be found unless fully qualified.
Use the following method to load content from an external URL:
<es:uricontent id="uriContent"
uri="http://www.beasys.com/index.html">
<%
out.print(uriContent);
%>
</es:uricontent>
The sample <es:uricontent> tag is available in public_html/portals/repository/portlets/_uri_example.jsp
Using example portlets
The /server/public_html/portals/repository/portlets directory of the WebLogic Personalization Server contains example portlets. The following table lists the name of each example portlet, its description, and its associated files.
Caution: The example portlets are intended for illustration purposes only and should not be used for production code.
HTML Tables vs. HTML Frames BEA WebLogic Commerce Server does not prevent the use of any kind of HTML, including HTML frames. You will see that the demos and examples that ship with the product are all reference implementations which use HTML tables.This tabular style is not a requirement of the product-you can write HTML however you like. If you choose to use HTML frames, keep the following considerations in mind:
If you choose to use frames, you will need to write HTML code to layout the portlets.
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|