Guidelines for Navigation within a Portlet

6-10 Oracle Fusion Middleware Developers Guide for Oracle Portal These calls cause the Parallel Page Engine to make the request to the resource and return it to the browser. For session-based providers, any cookies returned from the original initSession call to the provider are sent with the request back to the provider to maintain the right session context.

6.1.3 Guidelines for JavaScript

You may find the use of JavaScript useful within a portlet, but bear in mind the following guidelines within your portlets: ■ You should never use JavaScript to redirect the page in which the portlet is rendered. If you need to direct users elsewhere, you should do so in your portlet action handling code or open a new window in the browser. ■ Ensure that identifiers in your JavaScript are qualified. By qualifying your identifiers, you ensure that they are unique and do not clash with any other JavaScript on the page.

6.1.4 Guidelines for Mobile Portlets

Oracle Portal is capable of rendering its pages for both HTML and non-HTML mobile devices. When rendering for a mobile device, Oracle Portal requires portlets to generate content in a universal markup language called OracleAS Wireless XML. Many portlets, known as desktop portlets, generate only HTML responses and as such can only render themselves in standard HTML browsers. Some portlets, known as mobile portlets, generate only OracleAS Wireless XML responses. These portlets can render themselves on any device, including standard HTML browsers. Many portlets, though, take a hybrid approach that renders either HTML or OracleAS Wireless XML depending on the environment. These hybrid portlets can render themselves on any device, but they render best on standard HTML browsers. Although OracleAS Wireless XML is sufficient for HTML responses, it is not as expressive as HTML. Since portlets running in both a desktop and mobile environment are typically accessed using the desktop, developers commonly choose to create hybrid portlets that can provide the best possible rendition in the desktop environment. When building mobile portlets, you should adhere to the following guidelines: ■ Section 6.1.4.1, Declare Capabilities ■ Section 6.1.4.2, Declare a Short Title ■ Section 6.1.4.3, Implement Personalization of the Short Title ■ Section 6.1.4.4, Implement Link Mode ■ Section 6.1.4.5, Heed Device Information ■ Section 6.1.4.6, Tailor Personalization Pages For information on how to build mobile-enabled portlets, refer to Section 7.2.10, Enhancing Portlets for Mobile Devices .

6.1.4.1 Declare Capabilities

To properly manage portlets, Oracle Portal must know the set of content types a portlet generates. Oracle Portal uses this information in the following ways: ■ To restrict the Portlet Repository view in the Add Portlet dialog. Only those portlets capable of being rendered on the targeted page will appear in the Add Portlet dialog. For example, when a user invokes the Add Portlet dialog from a Creating Java Portlets 6-11 mobile design page, only portlets that indicate they can generate OracleAS Wireless XML responses are displayed. ■ To display an icon in the Portlet Repository view in the Add Portlet dialog that identifies portlets capable of being rendered on many devices. For example, when a user invokes the Add Portlet dialog from a standard design page, those portlets that are mobile capable are listed with the icon shown in Figure 6–2 to indicate they will also render on mobile devices. Figure 6–2 Mobile-enabled Icon ■ To display only those portlets registered with the capability of generating OracleAS Wireless XML when rendering a standard page on a mobile device. ■ To include only those portlets registered with the capability of generating OracleAS Wireless XML when creating a new mobile page based on an existing standard page.

6.1.4.2 Declare a Short Title

The small screen size of the typical mobile device limits the number of characters it can display in a single line without scrolling. Portlet titles, which appear as the menu item label when Oracle Portal renders the mobile page in a menu structure, are often too long for mobile displays. Hence, you can define a short title for your portlet. The short title replaces the standard title where display space is limited.

6.1.4.3 Implement Personalization of the Short Title

The standard portlet title represents the default portlet instance name when rendered in the header of a portlet on a standard page. The portlets short title represents the default portlet instance name when rendered as a menu item in a mobile page. Just as we recommend that portlets support personalizing the standard title, we also recommend that your portlets support personalizing the short title. This functionality enables the page designer or end user to give the instance a meaningful name.

6.1.4.4 Implement Link Mode

When Oracle Portal renders a standard page to the desktop, it assembles portlets on the page in the tabular layout defined by the page designer. Thus, Oracle Portal aggregates the content of many portlets on a single page. Because of their small displays, mobile devices cannot effectively display the content of multiple portlets on a single page. Instead, the pages portlets appear as links menu items. Users view portlet content by navigating the menu one portlet at a time. The menu item links typically use the portlets short name. Since well behaved portlets allow personalization of the short name and the portlet manages its own personalization data, the portlet must participate in rendering the menu item link. To enable this functionality, you can implement the Link mode for portlets. In response to a request to render a portlet in Link mode, a portlet generates a link to itself in the appropriate content type. For example, if the render requests HTML, the portlet returns an anchor tag. If the render requests OracleAS Wireless XML, the portlet returns a SimpleHref tag.

6.1.4.5 Heed Device Information

All requests, whether from mobile devices or the desktop, pass general device information. For example, one passed attribute identifies the device class, such as 6-12 Oracle Fusion Middleware Developers Guide for Oracle Portal pcbrowser, pdabrowser, or microbrowser cell phones. A portlet developer may use this attribute to adjust the responses layout or quantity of data.

6.1.4.6 Tailor Personalization Pages

A single portlet instance must maintain a single set of user personalizations spanning all devices, mobile and desktop. Therefore, the same personalization page appears even if the instance is shared between a standard and mobile page, and some fields apply only to one environment, desktop or mobile. In this situation, the portlet should identify these fields that pertain to only one environment. For example, a portlet might display a mobile-only section on its personalization page. Furthermore, because the mobile capability is configurable, a portlet could remove mobile-only references from its personalization page when it detects that the mobile functionality is disabled.

6.2 Introduction to Java Portlet Specification JPS and WSRP

Organizations engaged in enterprise portal projects have found application integration to be a major issue. Until now, users developed portlets using proprietary APIs for a single portal platform and often faced a shortage of available portlets from a particular portal vendor. All this changes with the introduction of the following standards: ■ Web Services for Remote Portlets WSRP ■ Java Portlet Specification JPS 1 based on JSR 168 These two standards enable the development of portlets that interoperate with different portal products, and therefore widen the availability of portlets within an organization. This wider availability can, in turn, dramatically increase an organizations productivity when building enterprise portals. WSRP is a Web services standard that enables the plug-and-play of visual, user-facing Web services with portals or other intermediary Web applications. Being a standard, WSRP enables interoperability between a standards-enabled container and any WSRP portal. WSRP defines the following: ■ Web Services Definition Language WSDL interface for the invocation of WSRP services ■ Markup fragment rules for markup emitted by WSRP services ■ The method to publish, find, and bind WSRP services and metadata JPS is a specification that defines a set of APIs to enable interoperability between portlets and portals, addressing the areas of aggregation, personalization, presentation, and security. JPS defines container services which provide the following: ■ A portlet API for coding portlet functionality ■ The URL-rewriting mechanism for creating user interaction within a portlet container ■ The security and personalization of portlets Oracle actively participates in the WSRP committee and is also a member of the expert group for JPS. 1 The Java Portlet Specification 1.0 arose from Java Specification Request 168 and the JSR168 Expert Group.