|
Oracle® Application Server Application Developer's Guide
10g Release 2 (10.1.2) Part No. B14000-01 |
|
 Previous |
 Next |
|
Oracle® Application Server Application Developer's Guide
10g Release 2 (10.1.2) Part No. B14000-01 |
|
|
Previous |
Next |
To make the sample application run within a portal framework, you have to make some changes to the application. The changes that you have to make are in the controller and the action handler objects. You also have to edit the links in the JSP files to make them work. The model layer (that is, the Employee and Benefit EJBs) remains the same.
Topics in this chapter:
Figure 9-1 shows how portal handles requests. This is important in understanding why you have to use APIs in the Oracle Application Server Portal Developer Kit to code your links and parameters.
A client sends a request to OracleAS for a portal page.
Portal handles the request. It queries the repository to get a list of portal providers that need to supply data to render the portal page.
Portal sends the request to each provider.
The providers process the request and return the appropriate data to portal.
Portal assembles the data into a page and returns the page to the client.
The screens for the application in a portal look the same as if the application were running outside of a portal. The only difference is that the portal pages contain tabs and icons as defined by users and administrators. Users and administrators can set up portals with different looks; see the portal documentation for details.
Figure 9-2 to Figure 9-6 show the pages of the application in a portal. You can compare these portal pages with the non-portal pages in Figure 3-1 and Figure 3-2.
Before you can run the sample application in a portal, you have to set up a few things outside the application as well as make some changes to the application itself.
You need to have a portal environment in which to run the application:
Set up a provider, and register the sample application with the provider.
Set up a portal page and define one of the regions on the page to display the sample application.
Figure 9-7 shows a sample portal page that contains the application. The tabs at the top of the page take you to different pages in the portal. You can have different tabs in your portal page.
Figure 9-7 A Portal Page Containing the Sample Application
You need to add some calls to the JPDK API to make your application run in a portal environment.
Update the links where you want to display another page within the portlet. If the file that contains the URL is an HTML page, you have to change it to a JSP page because you need to determine the URL dynamically.
Invoke the include method instead of forward. You have to use include because the portal needs to add data from other portlets. If you use forward, the portal does not have a chance to gather data from the other portlets.
Use the portletParameter method in the HttpPortletRendererUtil class to ensure that request parameters have unique names. This ensures that applications on the portal page read only their parameters and not parameters for other applications. This also enables applications to use the same parameter name; the method prefixes parameter names with a unique string for each application.
Make all URL paths absolute paths using the absoluteLink or the htmlFormActionLink method in the HttpPortalRendererUtil class, depending on the HTML tag.
When you need to link from one page in your application to another page within a portlet, you cannot simply specify the target page's URL in the href attribute of an <a> tag. Instead you have to do the following:
Use the parameterizeLink method in the HttpPortletRendererUtil class.
Add the next_page parameter to the request's query string to specify the target page or object.
The parameterizeLink method enables you to add a query string to the link. (If you do not have a query string in your link, you can just use the absoluteLink method.)
In the application, some of the places where you have to use the parameterizeLink method are:
to navigate from the ID page to the Info page
to navigate from the Info page to the Add Benefit or the Remove Benefit pages
The following files are affected: addBenefitToEmployee.jsp, removeBenefitFromEmployee.jsp, queryEmployee.jsp, error.jsp, and success.jsp.
The following example shows a link with two parameters in the query string.
Running outside a portal environment:
// from addBenefitsToEmployees.jsp
<a href="/empbft/controller?action=queryEmployee&empID=<%=empId%>">Query
the same employee</a>
Running within a portal environment:
// from addBenefitsToEmployees.jsp <% String fAction = HttpPortletRendererUtil.portletParameter(request, SessionHelper.ACTION_PARAMETER); String fEmpId = HttpPortletRendererUtil.portletParameter(request, SessionHelper.EMP_ID_PARAMETER); %> ... <a href="<%=HttpPortletRendererUtil.parameterizeLink(request, PortletRendererUtil.PAGE_LINK, HttpPortletRendererUtil.portletParameter(request, "next_page") + "=controller" + "&" + fAction + "=queryEmployee" + "&" + fEmpId + "=" + empId)%>">Query the same employee</a>
In the example above, you may have noticed that the target of the link, which is the controller, is specified as the value of the next_page parameter. The reason for this is that requests in a portal environment are always directed to the portal. The portal then forwards the requests to providers. For the provider to send the request to a specific target, you specify the target in the next_page parameter.
The name of the next_page parameter is specified in the provider.xml file (in the WEB-INF/providers/empbft directory in the webapp.war file). You can define the name of the parameter to be anything you want: it is the value of the pageParameterName tag.
In URLs for the application, the query string contains the next_page parameter. Portal sends the query string to the provider, which does the following:
The provider sees next_page as a special parameter.
The provider sends the request to the value of the parameter (controller).
The controller and other objects in the application process the request as normal.
// provider.xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?providerDefinition version="3.1"?>
<provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
<session>false</session>
<useOldStyleHeaders>false</useOldStyleHeaders>
<portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
<id>1</id>
<name>EmployeeBenefit</name>
<title>Employee Benefit Portlet</title>
<description>This portlet provides access to Employee Benefit Application.</description>
<timeout>10000</timeout>
<timeoutMessage>Employee Benefit Portlet timed out</timeoutMessage>
<showEdit>false</showEdit>
<showEditDefault>false</showEditDefault>
<showPreview>false</showPreview>
<showDetails>false</showDetails>
<hasHelp>false</hasHelp>
<hasAbout>false</hasAbout>
<acceptContentType>text/html</acceptContentType>
<renderer class="oracle.portal.provider.v2.render.RenderManager">
<renderContainer>true</renderContainer>
<contentType>text/html</contentType>
<showPage>index.jsp</showPage>
<pageParameterName>next_page</pageParameterName>
</renderer>
</portlet>
</provider>
This is a special case to link to the ID page of the application. You can use this link as the first link to the application.
To create a link to the ID page and display it in the portal page, use the following URL:
<%@ page import="oracle.portal.provider.v2.render.http.HttpPortletRendererUtil" %> <%@ page import="oracle.portal.provider.v2.render.PortletRendererUtil" %> ... <a href="<%=HttpPortletRendererUtil.parameterizeLink(request, PortletRendererUtil.PAGE_LINK, HttpPortletRendererUtil.portletParameter(request, "next_page") + "=controller")%>">
Note that the <a> tag uses JSP scriptlets. This means that this link has to be in a JSP file; it cannot be in an HTML file.
The href attribute uses JPDK APIs to ensure that the portal processes the link correctly, and that the application sends the request to the controller object. This chapter explains why you have to set up the link this way.
After OracleAS runs the JSP scriptlet, you end up with a link that looks something like:
http://<host>/servlet/page?_pageid=58,60&_dad=portal30&_schema=PORTAL30&
_pirefnull.next_page=controller
Call the include method instead of forward. You have to use include because the portal needs to add data from other providers. If you use forward, the portal does not have a chance to gather data from the other providers. See Figure 9-1.
Running outside a portal environment:
RequestDispatcher rq = req.getRequestDispatcher(forward); rq.forward(req, res);
Running within a portal environment:
RequestDispatcher rq = req.getRequestDispatcher(forward); rq.include(req, res);
The only class that calls forward is the AbstractActionHandler abstract class.
Ensure that parameter names on your page do not conflict with parameter names from other pages in the portal. To protect your parameters, call the portletParameter method in the HttpPortletRendererUtil class to ensure that your parameters have unique names. The method prefixes parameter names with a unique string for each application; this enables applications to use the same parameter name safely.
By using the method, you ensure that your applications on the portal page read only their parameters and not parameters from other applications.
You have to use the method to protect all your field names in your HTML forms. You have to do this when retrieving and setting values for the fields.
The following files are affected: AddBenefitToEmployee.java, Controller.java, QueryEmployee.java, RemoveBenefitFromEmployee.java, addBenefitToEmployee.jsp, removeBenefitFromEmployee.jsp, queryEmployee.jsp, error.jsp, and success.jsp.
When you use the methods to protect the parameters, the links look something like the following:
For add benefit actions:
http://<host>/servlet/page?_pageid=58%2C60&_dad=portal30&_schema=PORTAL30& _pirefnull.action=addBenefitToEmployee&_pirefnull.next_page=controller& _pirefnull.empID=125
For remove benefit actions:
http://<host>/servlet/page?_pageid=58%2C60&_dad=portal30&_schema=PORTAL30& _pirefnull.action=removeBenefitFromEmployee& _pirefnull.next_page=controller&_pirefnull.empID=125
For query employee actions:
http://<host>/servlet/page?_pageid=58%2C60&_dad=portal30&_schema=PORTAL30& _pirefnull.action=queryEmployee&_pirefnull.next_page=controller& _pirefnull.empID=125
The parameters used by the application are prefixed with _pirefnull. The other parameters in the URL are required by portal. Note also that the URL does not point to the controller directly. Instead it uses the _pirefnull.next_page parameter to indicate that the controller should handle the request.
The following example retrieves the values of two parameters.
Running outside a portal environment:
// from AddBenefitToEmployee.java String benefits[] = req.getParameterValues(SessionHelper.BENEFIT_PARAMETER); String client = req.getParameter(SessionHelper.CLIENT_TYPE_PARAMETER);
Running within a portal environment:
// from AddBenefitToEmployee.java import oracle.portal.provider.v2.render.http.HttpPortletRendererUtil; ... String fBenefits = HttpPortletRendererUtil.portletParameter(req, SessionHelper.BENEFIT_PARAMETER); String benefits[] = req.getParameterValues(fBenefits); String fClient = HttpPortletRendererUtil.portletParameter(req, SessionHelper.CLIENT_TYPE_PARAMETER); String client = req.getParameter(fClient);
If your parameter is a form element (for example, a checkbox or a hidden element), you have to call the portletParameter method to protect the name before you can use it. The following example shows how to set the BENEFIT_PARAMETER in a form:
// from addBenefitsToEmployees.jsp String fBenefits = HttpPortletRendererUtil.portletParameter( request, SessionHelper.BENEFIT_PARAMETER); <form ... > ... <input type="checkbox" name="<%=fBenefits%>" value="<%=b.getId()%>">
Make all URL paths absolute paths using the absoluteLink or the htmlFormActionLink method in the HttpPortalRendererUtil class, depending on the HTML tag.
You cannot use paths relative to the current page because OracleAS sends requests to portal first, and portal sends requests to providers. See Figure 9-1. When providers get the requests, the current path is the portal, not to the current page. By using absolute paths, you ensure that the provider can find the proper object.
The following files are affected: addBenefitToEmployee.jsp, removeBenefitFromEmployee.jsp, queryEmployee.jsp, error.jsp, and success.jsp.
Use the absoluteLink method to qualify paths in <a> and <link> tags.
Running outside a portal environment:
// from addBenefitToEmployee.jsp <link rel="stylesheet" type="text/css" href="css/blaf.css">
Running within a portal environment:
// from addBenefitToEmployee.jsp
<link rel="stylesheet" type="text/css"
href="<%= HttpPortletRendererUtil.absoluteLink(request,
"./css/blaf.css")%>"
>
Use the htmlFormActionLink method to qualify paths in the <form> tag.
Running outside a portal environment:
// from addBenefitToEmployee.jsp <form method="GET" action="/empbft/controller">
Running within a portal environment:
// from addBenefitToEmployee.jsp <form method="GET" action="<%=HttpPortletRendererUtil.htmlFormActionLink(request, PortletRendererUtil.PAGE_LINK)%>"> <%=HttpPortletRendererUtil.htmlFormHiddenFields(request, PortletRendererUtil.PAGE_LINK)%> <input type="hidden" name="<%=HttpPortletRendererUtil.portletParameter(request, "next_page")%>" value="controller">
Note that in the portal version the action attribute does not point to the controller. Instead, it points to the portal. The actual target for the form is specified in a hidden field called next_page. The value of the hidden field specifies the target.
When you use forms, you need to include additional parameters such as _dad and _schema. These parameters are needed by portal. To include these parameters, you can use the htmlFormHiddenFields method.
