7-72 Oracle Fusion Middleware Developers Guide for Oracle Portal
4.
Declare a short title. A short title is the short form of a portlets name and is for use where display space is limited. Specifically, Oracle Portal uses it when rendering
portlets as menu items in the page menu generated in response to a mobile request. If the portlet has registered a short title, Oracle Portal uses that as the
menu item label. Otherwise, it uses the portlets standard title. To declare a short title, you include the shortTitle tag in the portlets metadata section in
provider.xml:
portlet class=oracle.portal.provider.v2.DefaultPortletDefinition id2id
nameLotteryname titleLottery Portlettitle
shortTitleLotteryshortTitle ...
portlet
5.
Support short title personalization. Because the portlets short title is presented to the user as the menu item label that references the portlet instance on the page, we
recommend that all portlets allow users to personalize the short title. PDK-Java provides a base data class that manages both the short and standard title:
oracle.portal.provider.v2.personalize.NameValuePersonalizationObject The NameValuePersonalizationObject manages both the title and short
title. It contains methods for getting and setting the values. The personalization
Note: The ResourceRenderer and any portlet determines the
type of request it has received by the requests Accept header. The Accept header is a standard HTTP header that defines the acceptable
response types for a given request. It may be a list with multiple values if multiple content types are acceptable. When there are
multiple values, they are listed in order from most to least preferred. Oracle Portal controls the values passed to the portlet in the Accept
header. In the case of an HTML request, the Accept header is:
texthtml, textxml, textvnd.oracle.mobilexml These values indicate that Oracle Portal prefers an HTML response
but also accepts XML and OracleAS Wireless XML. For mobile requests, the Accept header is:
textvnd.oracle.mobilexml, textxml These values indicate that Oracle Portal prefers OracleAS Wireless
XML but also accepts general XML that contains a stylesheet reference that transforms to OracleAS Wireless XML.
The ResourceRenderer maps requested content type to the specific resource renderer by working through the Accept list in preference
order. Once it finds a match between an acceptable response type and a registered renderer, it dispatches the request to the resource. For
example, for HTML requests the ResourceRenderer will match the first entry, texthtml, to the declaration that defines lotto.jsp as
the texthtml handler. Likewise, when a mobile request is received, the ResourceRenderer matches the first entry,
textvnd.oracle.mobilexml, to the declaration that defines mlotto.jsp as the textvnd.oracle.mobilexml handler.
Enhancing Java Portlets 7-73
code is split into two parts, form display and form submit. The logic first acquires the current data personalization object. Next, it checks to see if this is a form
submit. If so, it updates the values in the data personalization object, writes them back to the repository, and returns. PDK-Java subsequently redirects back to this
same form but without the parameters that indicate it is a form submit causing the form to redisplay with the new values. In this situation, the JSP responds with the
personalization page including the current personalization values.
We recommend that portlets use this class or subclass to inherit this base support. The only personalization the lottery sample supports is these two titles. Hence, it
uses the NameValuePersonalizationObject class directly in custom.jsp:
page session=false import=oracle.portal.provider.v2. page import=oracle.portal.provider.v2.http.
page import=oracle.portal.provider.v2.render. page
import=oracle.portal.provider.v2.personalize.NameValuePersonalizationObject -- This page both displays the personalization form and processes it.
We display the form if there isnt a submitted title parameter, else we apply the changes --
PortletRenderRequest portletRequest = PortletRenderRequest request.getAttributeHttpCommonConstants.PORTLET_RENDER_REQUEST;
String title = request.getParameterlotto_title; String sTitle = request.getParameterlotto_short_title;
String actionParam = PortletRendererUtil.getEditFormParameterportletRequest;
String action = request.getParameteractionParam; NameValuePersonalizationObject data = NameValuePersonalizationObject
PortletRendererUtil.getEditDataportletRequest; Cancel automatically redirects to the page
-- so will only receive OK or APPLY if action = null {
data.setPortletTitletitle; data.setPortletShortTitlesTitle;
PortletRendererUtil.submitEditDataportletRequest, data; return;
} otherwise just render the form
title = data.getPortletTitle; sTitle = data.getPortletShortTitle;
TABLE BORDER=0 TR
TD WIDTH=20 P ALIGN=RIGHTTitle:
TD TD WIDTH=80
INPUT TYPE=TEXT NAME=lotto_title VALUE== title SIZE=20
TD TR
TR TD WIDTH=20
P ALIGN=RIGHTShort Title: TD
TD WIDTH=80 INPUT TYPE=TEXT NAME=lotto_short_title VALUE== sTitle
SIZE=20 MAXLENGTH=20
7-74 Oracle Fusion Middleware Developers Guide for Oracle Portal
TD TR
TABLE
6.
Support the rendering of personalized short titles. Once you add short title personalization, a portlet must take responsibility for rendering the portlet as a
menu item in the mobile page response. Because of the small screen displays on mobile devices, portlets arent rendered together. Users are presented with a menu
of links to portlets on a given page. The user navigates to each portlet through this menu to see the content. To better support this model, Oracle Portal provides Link
mode, where portlets generate Link references to themselves.
For HTML requests, Link mode generates an anchor tag, a href. For mobile requests, Link mode generates a simpleHref tag. Currently, Oracle Portal only
sends a Link mode request when assembling a mobile page response. Hence, you only need to support rendering the textvnd.oracle.mobilexml content type
for Link mode. If your portlet also has an HTML rendition, we recommend you also support HTML Link mode.
The lottery portlet example implements each Link rendition in a distinct JSP, as follows:
■
milotto.jsp contains the code to generate a textvnd.oracle.mobilexml Link response.
■
anchorlotto.jsp contains the code to generate a texthtml Link response.
The code for each is almost identical. Since the purpose of supporting Link mode is to render the personalized short title, the code first acquires the short title from
the repository. It then generates the appropriate link tag for the requested markup. The acquired short title is rendered as the links label. Since Oracle Portal is
responsible for creating the URL that references any particular usage of a portlet on a page, Oracle Portal creates the URL used in the link and passes it to the
portlet, which then uses the URL to create the link. The URL for the link is retrieved from the requests PageURL parameter. The code for milotto.jsp is as
follows:
page session=false contentType=textvnd.oracle.mobilexml page import=oracle.portal.provider.v2.http.HttpCommonConstants
page import=oracle.portal.provider.v2.render. page
import=oracle.portal.provider.v2.personalize.NameValuePersonalizationObject page import=oracle.portal.utils.xml.v2.XMLUtil
PortletRenderRequest portletRequest = PortletRenderRequest request.getAttributeHttpCommonConstants.PORTLET_RENDER_REQUEST;
NameValuePersonalizationObject data = NameValuePersonalizationObject PortletRendererUtil.getEditDataportletRequest;
String title = data.getPortletShortTitle; if short title is empty then use the title
if title == null || title.length == 0 title = data.getPortletTitle;
SimpleHref target== XMLUtil.escapeXMLAttribute portletRequest.getRenderContext.getPageURL
= XMLUtil.escapeXMLTexttitle SimpleHref
Enhancing Java Portlets 7-75
7.
Declare support for Link mode. Once you have implemented Link mode, you must update provider.xml to indicate the presence of Link mode. You declare
Link mode by adding code similar to the following to provider.xml:
portlet class=oracle.portal.provider.v2.DefaultPortletDefinition id2id
nameLotteryname ...
showLinktrueshowLink showEdittrueshowEdit
showEditToPublicfalseshowEditToPublic ...
portlet
8.
Bind the JSPs to the Link mode. The portlet must declare the mapping between the Show modes and the JSP renderers. The syntax for Link mode is similar to that for
Show mode.
portlet class=oracle.portal.provider.v2.DefaultPortletDefinition id2id
nameLotteryname ...
renderer class=oracle.portal.provider.v2.render.RenderManager contentTypetexthtmlcontentType
renderContainertruerenderContainer linkPage
class=oracle.portal.provider.v2.render.http.ResourceRenderer resourcePathhtdocslotteryanchorlotto.jspresourcePath
contentTypetexthtmlcontentType linkPage
linkPage class=oracle.portal.provider.v2.render.http.ResourceRenderer
resourcePathhtdocslotterymilotto.jspresourcePath contentTypetextvnd.oracle.mobilexmlcontentType
linkPage ...
renderer ...
portlet
7.2.10.1 Accessing Configuration, User, and Device Information
To better support mobile devices, Oracle Portal passes extra information to the portlet for use in generating its response. This information falls into three major categories, as
follows:
■
Section 7.2.10.1.1, Configuration Data
Note: The text being output as the URL and the short title label are
passed through special XML escape utilities. Because textvnd.oracle.mobilexml is an XML content type, generated
responses must adhere to XML rules, which require the escaping of specific characters. Unless generating static text, we recommend that
all text be escaped using the two supplied utilities. The reason for two utility methods is that the set of characters requiring escape varies
depending upon whether the text is a tag attribute value or a tag value.
7-76 Oracle Fusion Middleware Developers Guide for Oracle Portal
■
Section 7.2.10.1.2, User Data
■
Section 7.2.10.1.3, Device Information
7.2.10.1.1 Configuration Data Oracle Portal sends a flag that indicates whether the
mobile function is enabled when requesting that the portlet render its personalization or edit pages. Portlets can use this information to exclude or include mobile specific
attributes in their personalization pages as appropriate.
The portlet accesses this information using the PortletRenderRequest object: ...
if portletRequest.getPortalConfig.isMobileEnabled { ...
} ...
7.2.10.1.2 User Data OracleAS Wireless adds the user location to the requests it
forwards to Oracle Portal for response. This user location information is determined by the users actual location, if the users device has this support, or a profiled location.
The user location is exposed by the ProviderUser object, which you can access from the PortletRenderRequest object. Portlets that are location aware can use this
information to adjust the content they generate.
... UserLocation location = portletRequest.getUser.getLocation;
if location = null { ...
} ...
7.2.10.1.3 Device Information On each request, Oracle Portal sends characteristics about
the requesting device to the portlet. This information is sent for all portlet requests, not just mobile requests. The information classifies the type of device making the request,
its layout orientation, the maximum response size the device can handle, and an indication of whether the connection with the device is secure.
Table 7–3 describes the
available device types.
Portlets may choose to alter the layout or representation of the content in their response based on the type of device making the request. For example, a portlet may
break a wide table into a series of screens that link column groups together for small screen devices.
Table 7–3 Device Classes
Class Description
voice Indicates a voice-only device, such as a normal telephone calling
a voice access number. micromessenger
Indicates text messenging devices, such as SMS phones or pagers.
messenger Indicates general messenging devices, such as e-mail.
microbrowser Indicates a small size display device, which supports a markup
browser, such as a WAP phone. pdabrowser
Indicates a medium size display device, such as a Palm or PocketPC.
pcbrowser Indicates a large size display device used with desktop
browsers.
Enhancing Java Portlets 7-77
The maximum response size is a hint that a portlet can use to constrain the amount of data it returns. The size is expressed in bytes. A maximum response size of 0 means
the size is unknown.
The portlet accesses this information using the PortletRenderRequest object. ...
DeviceInfo deviceInfo = portletRequest.getDeviceInfo; switch deviceInfo.getDeviceClass {
case DeviceInfo.DeviceClass.MICROBROWSER: renderMicroBrowserportletRequest;
break; default:
renderDefaultportletRequest; break;
} ...
7.2.10.2 Modifying Navigation for Mobile Portlets
Much of the information in Section 7.2.3.3.4, Implementing Navigation within a
Portlet is also relevant to the development of mobile portlets, but some of the utilities
referenced are specific to portlets that render HTML. For portlets that render SimpleResult, the equivalent utilities shown in
Table 7–4 are available.
The following example illustrates how to adapt the thesaurus sample for a mobile-enabled portlet. Note that, when deployed as a mobile portlet, both sets of JSPs
HTML and SimpleResult are deployed. These JSPs complement their HTML counterparts, they do not replace them. Notice also that the JSPs use SimpleResult
as their markup and the value of the navigation parameter has changed such that it points to the next mobile JSP rather than the next desktop JSP.
mThesaurusForm.jsp:
PortletRenderRequest pRequest = PortletRenderRequest request.getAttributeHttpCommonConstants.PORTLET_RENDER_REQUEST;
String paramNameQ = q; String qualParamNameQ =
HttpPortletRendererUtil.portletParameterpRequest, paramNameQ; -- Output the MXML content --
SimpleText SimpleTitleThesaurusSimpleTitle
SimpleTextItemEnter the word you wish to search for:SimpleTextItem SimpleForm
method=POST target== UrlUtils.htmlFormActionLinkpRequest,UrlUtils.PAGE_LINK
=UrlUtils.mxmlFormHiddenFields pRequest.getRenderContext.getPageURL
= UrlUtils.emitMxmlHiddenField HttpPortletRendererUtil.portletParameterrequest, next_page,
Table 7–4 Equivalent HTML and SimpleResult Utilities
HTML Utilities SimpleResult Utilities
UrlUtils.constructHTMLLink UrlUtils.constructMXMLLink
UrlUtils.htmlFormHiddenFields UrlUtils.mxmlFormHiddenFields
UrlUtils.emitHiddenField UrlUtils.emitMxmlHiddenField
7-78 Oracle Fusion Middleware Developers Guide for Oracle Portal
htdocspathmThesaurusLink.jsp SimpleFormItem type=text size=20 name== qualParamNameQ
value= SimpleForm
SimpleText
mThesaurusLink.jsp:
PortletRenderRequest pRequest = PortletRenderRequest request.getAttributeHttpCommonConstants.PORTLET_RENDER_REQUEST;
String paramNameQ = q; String paramNameNextPage = next_page;
String qualParamNameQ = HttpPortletRendererUtil.portletParameterpRequest, paramNameQ;
String qualParamNameNextPage = HttpPortletRendererUtil.portletParameterpRequest, paramNameNextPage;
String paramValueQ = pRequest.getQualifiedParameterparamNameQ; -- Output the MXML content --
SimpleText SimpleTitleWords similar to = paramValueQ SimpleTitle
Thesaurus t = new Thesaurus; String[] relatedWords = t.getRelatedWordsparamValueQ;
NameValue[] linkParams = new NameValue[2]; linkParams[0] = new NameValue
qualParamNameNextPage, htdocspathmThesaurusLink.jsp; for int i=0; irelatedWords.length; i++
{ linkParams[1] = new NameValue
qualParamNameQ, relatedWords[i]; SimpleTextItem
= relatedWords[i] SimpleBreak
= UrlUtils.constructMXMLLink pRequest,
pRequest.getRenderContext.getPageURL, words related to + relatedWords[i] + ,
, linkParams,
true, true
SimpleTextItem }
SimpleTextItem SimpleHref target==XMLUtil.escapeXMLAttribute
pRequest.getRenderContext.getPageURL Reset Portlet
SimpleHref SimpleTextItem
SimpleText
Enhancing Java Portlets 7-79
7.2.11 Writing Multilingual Portlets
This section shows you how to build a Java portlet that can be rendered in different languages. The language used in your portlet will depend upon on the language
setting that has been chosen in the portal that is displaying it.
Once you have completed this section you will be able to write portlets that support as many or as few languages as you wish. You will also be able to convert your existing
portlets to support multiple languages. Once a portlet is written to support multiple languages, it is easy to plug in new languages. The basic model for multilingual Java
portlets is similar to the standard Java Internationalization model. If you already know about Java Internationalization, you should find this process very familiar.
7.2.11.1 Assumptions
To perform the tasks in this section, we are making the following assumptions:
1.
You have followed through and understood Section 6.5, Building Oracle
PDK-Java Portlets with Oracle JDeveloper .
2.
You built a portlet using the wizard and successfully added it to a page.
7.2.11.2 Internationalizing Your Portlet
This consists of the following two tasks:
■
Section 7.2.11.2.1, Providing Translations for Portlet Content
■
Section 7.2.11.2.2, Providing Translation for Portlet Attributes
7.2.11.2.1 Providing Translations for Portlet Content In
Section 6.5, Building Oracle PDK-Java Portlets with Oracle JDeveloper
, you created a portlet using the Java Portlet Wizard. The basic message created by the wizard is only available in one language and
the text displayed is hard-coded in to the portlets renderer class. To make your portlets available in multiple languages, you have to store such language dependent
elements in their own resource bundles.
Creating Resource Bundles For each language you want your portlet to be available in, you will need a resource
bundle. You will also need to create a resource bundle to use when there is no resource bundle corresponding to the language setting chosen in the portal. Perform the
following tasks:
■
Create a Default Resource Bundle
Perform the following steps:
1.
In Oracle JDeveloper, create a Java class called MyProviderBundle that extends ListResourceBundle from the java.util.package. The class
should contain a multi-dimensional array of objects that holds key-value pairs representing each of the language dependent elements from your JSP show
page. This implementation is demonstrated in the following code:
package mypackage2; import java.util.ListResourceBundle;
public class MyProviderBundle extends ListResourceBundle {
public static String HELLO_MSG = MyPortletHelloMessage; public static String INFO_MSG = MyPortletInfoMessage;
public Object[][] getContents {
7-80 Oracle Fusion Middleware Developers Guide for Oracle Portal
return contents; }
static private final Object[][] contents = {
{HELLO_MSG, Hello}, {INFO_MSG, This is the show page of the portlet and it is being generated
in the default language} };
}
2.
Save MyProviderBundle.
■
Creating Resource Bundles for Other Supported Languages
Now you must create a resource bundle class for each language you want your portlet to support. Each of these classes must be named the same as your default
resource bundle class, but with a language code appended to the end. For example, if you want to support the French language, create a Java class named
MyProviderBundle_fr. The language code fr is the same as the code that will be used by the locale object in the portal if the language setting is set to French
For more information on Locales, search for java.util.Locale in the Javadoc. Refer to the Javadoc on OTN by clicking Java Doc API on the Portlet Development
page available at
http:www.oracle.comtechnologyproductsiasportalportlet_ development_10g1014.html
When you change the language setting in Oracle Portal, you change the value of the current locale object and therefore the locale objects language code. These
language codes adhere to the ISO:639 codes for representation for names of languages. To create resource bundles for other supported languages, perform the
following steps:
1.
To create a French resource bundle, create a Java class named MyProviderBundle_fr, as described earlier.
2.
Using your default resource bundle as a template, replace the English language strings with their French equivalents. An example is as follows:
package mypackage2; import java.util.ListResourceBundle;
public class MyProviderBundle_fr extends ListResourceBundle
{ public Object[][] getContents
{ return contents;
} static private final Object[][] contents =
{ {MyProviderBundle.HELLO_MSG, Bonjour},
{MyProviderBundle.INFO_MSG, Cette page est le show mode de la portlet et est generee dans la langue par defaut.}
}; }
3.
Save MyProviderBundle_fr.
Enhancing Java Portlets 7-81
4.
Repeat steps 1 through 3 for every language that you wish to create a resource bundle for, updating the class name with the appropriate language code and
the message strings with their equivalent in the appropriate language.
Updating Your Renderer To make use of the resource bundles you just created, you need to edit the JSP show
page and replace the hard-coded messages with references that will pickup the messages at run time from the resource bundle that corresponds most closely with the
locale object of the portal. To update your renderer, perform the following steps:
1.
Open the JSP that represents your show page and change the following: page contentType=texthtml; charset=windows-1252
import=oracle.portal.provider.v2.render.PortletRenderRequest import=oracle.portal.provider.v2.http.HttpCommonConstants
import=java.util.ResourceBundle
PortletRenderRequest pReq = PortletRenderRequest request.getAttributeHttpCommonConstants.PORTLET_RENDER_REQUEST;
-- Get a resource bundle object for the current language. -- ResourceBundle b =
ResourceBundle.getBundlemypackage2.MyProviderBundle,pReq.getLocale;
-- Pull the message from the appropriate resource bundle. -- P = b.getStringmypackage2.MyProviderBundle.HELLO_MSG
= pReq.getUser.getName .P P = b.getStringmypackage2.MyProviderBundle.INFO_MSG P
2.
Save your JSP page. Now you can refresh your portlet and view the changes
Figure 7–12 .
Figure 7–12 Portlet in English
To view the French greeting, you set the language in the Set Language portlet to French instead of English
Figure 7–13 .
Figure 7–13 Portlet in French
