Current Limitations for Web Clipping

5-28 Oracle Fusion Middleware Developers Guide for Oracle Portal 6 Creating Java Portlets 6-1 6 Creating Java Portlets This chapter explains how to create Java portlets based on the Java Portlet Specification JSR 168 or the Oracle Portal Developer Kit-Java PDK-Java using the JSR 168 Java Portlet Wizard and Java Portlet Wizard in Oracle JDeveloper. This chapter includes the following sections: ■ Section 6.1, Guidelines for Writing Java Portlets ■ Section 6.2, Introduction to Java Portlet Specification JPS and WSRP ■ Section 6.3, Building JPS-Compliant Portlets with Oracle JDeveloper ■ Section 6.4, Introduction to Oracle PDK-Java ■ Section 6.5, Building Oracle PDK-Java Portlets with Oracle JDeveloper The source code for many of the examples referenced in this chapter is available as part of PDK-Java. You can download PDK-Java from the Oracle Portal Developer Kit PDK page on Oracle Technology Network OTN: http:www.oracle.comtechnologyproductsiasportalpdk.html When you unzip PDK-Java, you will find the examples in a zip file: ..pdkjpdkv2src.zip To access the Javadoc reference for PDK-Java, extract jpdk.war from inside of: ..pdkjpdkv2jpdk.ear Then unzip jpdk.war. The Javadoc is located in a folder called apidoc.

6.1 Guidelines for Writing Java Portlets

When you write your portlets in Java for either the Java Portlet Specification JPS or PDK-Java, you should follow the best practices described in this section, which are as follows: ■ Section 6.1.1, Guidelines for Show Modes ■ Section 6.1.2, Guidelines for Navigation within a Portlet ■ Section 6.1.3, Guidelines for JavaScript ■ Section 6.1.4, Guidelines for Mobile Portlets 6-2 Oracle Fusion Middleware Developers Guide for Oracle Portal

6.1.1 Guidelines for Show Modes

Show mode exhibits the runtime portlet functionality seen by users. JPS offers some modes not offered by PDK-Java and vice versa. If you are coding portlets to JPS, you can declare custom portlet modes in portlet.xml that map to the extra modes offered by PDK-Java, or to accommodate any other functionality you may want to provide. For example, the JSR 168 Java Portlet Wizard for JPS portlets includes a custom mode call print, which you can use to provide a printer friendly version of the portlet. Defining custom modes is especially useful if the portlet must interoperate with portal implementations from other vendors The different Show modes that a portlet may have, each with its own visualization and behavior, are discussed in the following sections: ■ Section 6.1.1.1, Shared Screen Mode View Mode for JPS ■ Section 6.1.1.2, Edit Mode JPS and Pdk-Java ■ Section 6.1.1.3, Edit Defaults Mode JPS and PDK-Java ■ Section 6.1.1.4, Preview Mode JPS and PDK-Java ■ Section 6.1.1.5, Full Screen Mode PDK-Java ■ Section 6.1.1.6, Help Mode JPS and Oracle Portal ■ Section 6.1.1.7, About Mode JPS and PDK-Java ■ Section 6.1.1.8, Link Mode PDK-Java

6.1.1.1 Shared Screen Mode View Mode for JPS

A portlet uses Shared Screen mode known as View mode in JPS to appear on a page with other portlets. This is the mode most people think about when they envision a portlet. A JPS portlet must have a view mode, the rest are optional. When developing portlets, you must consider all of the factors that may influence the portlet’s appearance on the page, such as the portlet’s containing object and the other portlets with which your portlet will share a page. In Oracle Portal, portlets are rendered inside HTML table cells when in Shared Screen mode. This means a portlet can display only content that can be rendered within a table cell, including, among other technologies, HTML, plug-ins, and Java applets. The actual size of the table cell is variable depending on user settings, the browser width, and the amount and style of content in the portlet.

6.1.1.1.1 HTML Guidelines for Rendering Portlets Plain HTML is the most basic way to

render portlets and provides a great deal of flexibility to portlet developers. You can use almost any standard HTML paradigm, such as links, forms, images, and tables, as long as it can display within an HTML table cell. Improperly written HTML may appear inconsistently across different browsers and, in the worst case, could cause parts of your page not to appear at all. Ensure that you adhere to the following rules: ■ Use standard HTML. The official HTML specification is available from the W3C more information available at: http:www.w3.orgMarkUp . ■ Avoid unterminated and extraneous tags. The behavior of pages with improperly terminated tags is unpredictable because it depends on what the browser chooses to do. Tools like weblint http:www.weblint.org and HTML Tidy http:www.w3.orgPeopleRaggetttidy can help detect and fix hanging and unnecessary tags. Creating Java Portlets 6-3 ■ Avoid elements that cannot be rendered properly in an HTML table cell. Some constructs cannot be used simply because they do not display correctly in a table cell. Frames, for example, do not appear when inserted in a table. ■ Keep portlet content concise. Do not try to take full screen content and expose it through a small portlet. You will only end up with portlet content too small or cramped for smaller monitors. Full screen content is best viewed in Full Screen mode of PDK-Java. ■ Do not create fixed-width HTML tables in portlets. You have no way to tell how wide a column your portlet will have on a users page. If your portlet requires more room than given, it might overlap with another portlet in certain browsers. ■ Avoid long, unbroken lines of text. The result is similar to what happens with wide fixed-width tables. Your portlet might overlap other portlets in certain browsers. ■ Check behavior when resizing the page. Test your portlets behavior when the browser window is resized to ensure that it works in different browser window sizes. ■ Check behavior when the default browser font changes. People may choose whatever font size they wish and they can change it at any time. Your portlet should handle these situations gracefully. The HTML you use also impacts the perceived performance of your site. Users judge performance based on how long it takes for them to see the page they requested, and browsers require time to interpret and display HTML. Given that, you should consider the following: ■ Avoid deeply nested tables. Deeply nested tables slow performance dramatically in some older browser versions. Oracle Portal draws several levels of tables to render portlets. If your portlets use tables within tables, your users may have to wait quite a while for those pages to render. ■ Avoid lengthy, complex HTML. Portlets share a page with other portlets. Thus, portlet generation times can significantly effect the overall performance of the page. If portlets must render complex HTML or wait for external resources, such as third party applications, it can greatly slow the rendering of the page.

6.1.1.1.2 Cascading Style Sheet Guidelines for Rendering Portlets The fonts and colors of

every portlet on a page should match the style settings chosen by the user. To accomplish this goal, these style selections are embedded automatically using a Cascading Style Sheet CSS on each Oracle Portal page. The portlets access these settings for their fonts and colors, either directly or using the API. While different browsers have implemented varying levels of the full CSS specification, Oracle Portal uses a very basic subset of this specification to allow for consistent fonts and colors. CSS implementation levels should not affect the consistency of your pages across browsers. Follow these guidelines for using CSS: ■ Use CSS instead of hard coding. Hard coding fonts and colors is extremely dangerous. If you hard code fonts and colors, your portlet may look out of place when the user changes the page style settings. Since you have no way of knowing the users font and color preference choices, you might also choose to hard code a font color that turns out to be the same as the users chosen background color, in which case your portlet appears to be invisible to that user. ■ Use the CSS APIs to format your text. The stylesheet definition is available at the top of Oracle Portal pages, but you should not call it directly. Instead, use the APIs