31 Creating Portlets with the Portlet Wizard

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) in a WebCenter portlet application, using the Create JSR 168 Java Portlet and Create Oracle PDK-Java Portlet wizards.

This chapter includes the following sections:

31.1 Introduction to Java Portlets

This section includes the following sections:

31.1.1 Introduction to Standards-Based Java Portlets

Organizations engaged in custom WebCenter application 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 changed with the introduction of the following standards:

  • Web Services for Remote Portlets (WSRP)

  • Java Specification Request (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 organization's productivity when building custom WebCenter applications.

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 methods to publish, find, and bind WSRP services and metadata

JSR 168 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. JSR 168 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 JSR 168.

Note:

HTML forms can be submitted using either the get or post method, but the WSRP standard only requires the consumer (custom WebCenter application) to use the post method. Support of the get method is optional according to the standard. Since application consumers are not required to support the get method, Oracle recommends that you use the post method when developing your portlets.

The Relationship Between WSRP and JSR 168

WSRP is a communication protocol between a portlet client, for example, a WebCenter application, and a portlet container running on a remote server. JSR 168 describes the Java Portlet API for running portlet applications. Combining these standards enables developers to integrate their applications from any internal or external source as portlets with WSRP portals. Building pages becomes as simple as selecting portlets from the JDeveloper Component Palette.

Figure 31-1 shows the architecture of the WSRP specification.

Note:

Figure 31-1 illustrates the use of JSR 168 portlets with WSRP.

Figure 31-1 WSRP Specification Architecture

Shows JPS portlet containers and WSRP portal.
Description of "Figure 31-1 WSRP Specification Architecture"

Oracle WebCenter Framework can support communication between the custom WebCenter application and both the new Java Portlet APIs and our existing APIs (PDK-Java).

Figure 31-2 shows the architecture of the WSRP support. Notice that the JSR 168-compliant portlet container uses the WSRP protocol for communication and the PDK-Java portlet container uses Oracle's proprietary SOAP protocol for communication.

Figure 31-2 Oracle WebCenter Portlet Architecture

Shows PDK-Java and JPS portlets and WSRP portal.
Description of "Figure 31-2 Oracle WebCenter Portlet Architecture"

For a description of how JSR 168 security concepts are exposed through WSRP, see Section 37.12, "Securing Identity Propagation Through WSRP Producers with WS-Security."

31.1.2 Introduction to PDK-Java Portlets

PDK-Java gives you a framework to simplify the development of Java portlets by providing commonly required utilities and enabling you to leverage existing development skills and application components such as JSPs, servlets, and static HTML pages. PDK-Java also enables you to create portlets without having to deal directly with the complexity of communications between Oracle WebCenter Framework and producers.

The PDK-Java framework is divided into the following areas:

  • The Producer Adapter insulates the developer from the HTTP syntax defined by Oracle WebCenter Framework for communication with web producers. It translates the information passed between Oracle WebCenter Framework and your Java web producer. Without an adapter, your producer would not only manage portlets, but it would also have to communicate this information directly to Oracle WebCenter Framework in the expected language. The adapter eliminates the need for your web producer to understand the portal language and vice-versa.

  • The Producer Interface defines the APIs (functions) required by your Java implementation to integrate with the Producer Adapter. The Producer Adapter receives messages from the custom WebCenter application, translates them into calls to the Producer Interface, and translates the producer's response into a format that the application can understand. The Producer Interface contains a set of Java classes that define the methods your producer implements and, in often, provides a standard implementation. Some of the primary classes are as follows:

    • ProviderDefinition (oracle.portal.provider.v2.ProviderDefinition)

    • ProviderInstance (oracle.portal.provider.v2.ProviderInstance)

    • PortletDefinition (oracle.portal.provider.v2.PortletDefinition)

    • PortletInstance (oracle.portal.provider.v2.PortletInstance)

    • ParameterDefinition (oracle.portal.provider.v2.ParameterDefinition)

    • EventDefinition (oracle.portal.provider.v2.EventDefinition)

  • The Producer Runtime provides a base implementation that follows the specification of the Producer Interface. The Producer Runtime includes a set of default classes that implement each of the Producer Interfaces and enables you to leverage the rendering, personalization, and security frameworks provided with PDK-Java. These classes and the associated frameworks simplify the development of a producer by implementing common functions for Oracle WebCenter Framework requests and providing a declarative mechanism for configuring the producer. Using the Producer Runtime, you can focus your development efforts on the portlets themselves rather than the infrastructure needed to communicate with the custom WebCenter application. If the standard behavior of the Producer Runtime does not meet your requirements, then you can easily extend or override specific behaviors. Some of the primary classes are as follows:

    • DefaultProviderDefinition (oracle.portal.provider.v2.DefaultProviderDefinition)

    • DefaultProviderInstance (oracle.portal.provider.v2.DefaultProviderInstance)

    • DefaultPortletDefinition (oracle.portal.provider.v2.DefaultPortletDefinition)

    • DefaultPortletInstance (oracle.portal.provider.v2.DefaultPortletInstance)

    • PortletRenderer (oracle.portal.provider.v2.render.PortletRenderer)

    • PortletPersonalizationManager (oracle.portal.provider.v2.personalize.PortletPersonalizationManager)

    • PortletSecurityManager (oracle.portal.provider.v1.http.DefaultSecurityManager)

  • The Producer Utilities provide methods for simplifying the rendering of portlets. The utilities include methods for constructing valid links (hrefs), rendering the portlet's container (including the header), rendering HTML forms that work within a page, and supporting portlet caching.

You can find the JavaDoc reference for the PDK-Java on Oracle Technology Network (OTN) at:

http://www.oracle.com/technology/products/webcenter/portlet_download.html

31.2 Creating Java Portlets

Before you begin you should make sure:

Note:

The figures in this section were taken with the default Look and Feel and Theme settings in JDeveloper (Oracle and Fusion Blue). If you have changed these settings, then what you see on your screen may vary slightly, but the content and functionality remains the same. To change the Look and Feel and Theme settings, select Preferences from the Tools menu, and then select Environment.

This section includes the following subsections:

31.2.1 How to Create a JSR 168 Java Portlet

Using the Create JSR 168 Java Portlet wizard in JDeveloper you can expose your portlet over WSRP 2.0 quickly and easily. This wizard supports both WSRP 1.0 and WSRP 2.0. If you choose to create a WSRP 2.0 portlet, then an additional page appears in the wizard for the WSRP 2.0 enhancements.

In the Create JSR 168 Java Portlet wizard, you can choose which portlet modes you want to implement and the implementation method (JSP, HTTP servlet, Java class, or HTML) to use for each mode. The wizard then creates a simple implementation for each of the selected modes.

To create a JSR 168 Java portlet using the JDeveloper wizard:

  1. In the JDeveloper Application Navigator, open the application under which you want to create your portlet.

    The application must be scoped for portlet creation. An easy way to achieve this is to use a Portlet Producer Application. WebCenter Applications are not scoped for portlet creation.

  2. Right-click the project under which you want to create your portlet, and choose New.

  3. In the New Gallery, expand Web Tier, select Portlets and then Standards-based Java Portlet (JSR 168), and click OK.

    Note:

    Selecting Standards-based Java Portlet opens the wizard for creating JSR 168-compliant portlets. Selecting Oracle PDK-Java Portlet opens the wizard for creating PDK-Java portlets.
  4. On the General Portlet Information page of the Create JSR 168 Java Portlet wizard (Figure 31-3), replace the default name provided in the Name field with one that better describes the purpose of the portlet.

    Figure 31-3 The General Portlet Information Page

    Shows General Portlet Properties page.
    Description of "Figure 31-3 The General Portlet Information Page"

  5. In the Class field, enter a name for the class for the portlet. You can accept the default name provided or supply your own. If you supply your own name, it must be a valid Java name.

  6. From the Package dropdown list, select the package in which to create the class.

    Click the Browse button to find packages within the project, if required. If you do not select a specific package, the wizard uses the default package of the project.

  7. From the Default Language dropdown list, select the default language that your portlet supports. The wizard uses English by default.

  8. Select Enable users to edit portlet content if you want your portlet to support Edit mode. In the wizard, this option is selected by default.

    If you select this option, you can specify the details for the Edit mode later on in the wizard.

  9. Select Enable inter-portlet communication using Oracle WSRP V2 extensions to create a portlet that supports Oracle WSRP 2.0 extensions and then click Next.

    Selecting this option creates the oracle-portlet.xml file that is used for WSRP 2.0 features, such as navigation parameters. The WSRP 2.0 standard extends WSRP 1.0 by including support for inter-portlet communication (through navigation parameters) and export and import of portlet customizations.

    Note:

    JSR 168 portlets built with the Oracle WSRP V2 extensions can be consumed by any consumer that supports WSRP 2.0.
  10. On the Additional Portlet Information page (Figure 31-4), in the Portlet Title field, enter a descriptive title for your portlet.

    The portlet title is displayed in the Resource Palette or Application Resources panel, so make the title something to help users decide whether the portlet is useful to them. The portlet title is also displayed on the portlet header when the portlet appears on a page.

    Figure 31-4 The Additional Portlet Information Page

    Shows Name and Attribution page.
    Description of "Figure 31-4 The Additional Portlet Information Page"

  11. The display name, short title, description, and keyword attributes are not implemented in custom WebCenter applications. You do not need to enter any values for these fields unless your portlet is likely to be consumed by other applications. For example, Oracle Portal uses the portlet display name in the Portlet Repository.

  12. At this point in the wizard, you can click Finish to create the portlet immediately, using the default values for all remaining settings.

    To provide additional details for your portlet, click Next and follow the remaining steps.

  13. On the Content Types and Portlet Modes page (Figure 31-5), to add a content type, select an existing content type (for example, text/html) and then click Add. In the Content Types dialog move the desired content types to the Selected list and then click OK.

    By default, your portlet displays its content using the text/html content type.

    Figure 31-5 The Content Types and Portlet Modes Page

    Shows Content Types and Portlet Modes page.
    Description of "Figure 31-5 The Content Types and Portlet Modes Page"

  14. To add another portlet mode to your portlet, select an existing mode (for example, view) under the appropriate content type and then click Add. In the Portlet Modes dialog, move the desired modes to the Selected list and then click OK.

    By default, your portlet includes View mode. If you selected Enable users to edit portlet content on the General Portlet Properties page, then your portlet also includes Edit mode. For more information about portlet modes, see Section 31.2.5.1, "Guidelines for Portlet Modes."

  15. Select each of the portlet modes and specify the implementation method for rendering content.

    The wizard generates a portlet dispatcher Java class and any other required files for each portlet mode. The exact nature of this class and any other generated files depends on the chosen implementation method:

    • Select Generate JSP to generate a skeleton JSP file for the portlet mode. Enter a name for the JSP in the corresponding field, or accept the default.

      When you complete the wizard, the generated JSP displays in the Application Navigator where you can select it for further development. This is the default selection for all portlet display modes.

    • Select Generate ADF-Faces JSPX to generate a page to which you can add ADF-Faces components. Enter a name for the JSPX in the corresponding field, or accept the default.

      This applies to all portlet modes. If any portlet mode uses this selection, the wizard generates a portlet application which uses the Oracle JSF Portlet Bridge.

    • Select Map to Path to map the portlet mode to a web resource in the portlet application, such as a page. The resource is not generated by the wizard. Enter the name and path in the corresponding field. You can create this resource after completing the wizard if necessary.

      With this selection, you must write the targeted resource or file yourself. The target could be, for example, a JSP, a servlet, or an HTML file. This selection enters code in the generated portlet Java class that routes requests for the given mode to the specified target.

    • Select Custom Code to implement the portlet mode through a custom coded object. You must create this object later. This selection generates a skeleton method to render content (private void doMODE_NAMECONTENT_TYPE) in the generated portlet java class. You must update this code to render useful content.

  16. Click Next.

    If you selected Enable users to edit portlet content on the General Portlet Information page earlier in the wizard, then the Customization Preferences page appears where you can create additional customization preferences. Go to step 17.

    If you did not select this option, the Security Roles page appears. Go to step 22.

  17. On the Customization Preferences page (Figure 31-6), click Add to add a new customization preference to the portlet.

    Customization preferences enable users of the portlet to specify values for the portlet at runtime. By default, the wizard includes a preference to enable users to customize the portlet title.

    Figure 31-6 The Customization Preferences Page

    Shows Customization Preferences page.
    Description of "Figure 31-6 The Customization Preferences Page"

  18. In the Add New Preference dialog, in the Name field, enter a name for the new preference.

    The name must be unique in the portlet. Use only letters, numbers, and the underscore character.

  19. In the Default Values field, enter one or more default values for the new preference. Separate multiple values with commas.

  20. To make the preferences translatable, select the Translate checkbox and then click OK.

    JDeveloper generates a resource bundle class for translatable preferences, with strings for which you can obtain translations. At runtime, the portlet references the resource bundle entries.

    Note:

    The Name is always translated, but there is not always a requirement to translate the Default Values. For example, if the value is an integer, then no translation is needed.
  21. Repeat the preceding steps to add more preferences. When you are done click Next.

  22. On the Security Roles page (Figure 31-7), to add an existing security role to your portlet, select the security role and move it to the Selected list.

    Security roles enable you to set tiered levels of access to the portlet. For example, a View user can view the portlet but cannot edit it; a Customize user can customize portlet settings; a Manage user can perform all available functions associated with the portlet.

    The Available list displays the security roles defined for the application in which you are creating the portlet. Moving a security role to the Selected list creates a reference of the security role in the application's portlet deployment file (portlet.xml) that refers to the security role in the application's web deployment file (web.xml).

    Figure 31-7 The Security Roles Page

    Shows Security Roles page.
    Description of "Figure 31-7 The Security Roles Page"

  23. To define a new security role, click New Security Role.

  24. In the Create New Security Role dialog, specify a name and description for the role and then click OK to add the role to the list of available roles.

    The name should be unique within the application. The description should provide details about the access privileges and restrictions this role has on the portlet.

    You can also manually create security roles in the web.xml file.

  25. Click Next.

  26. On the Caching Options page (Figure 31-8), to enable caching for your portlet, select Cache Portlet.

    Selecting this option indicates that portlet caching is managed by the portlet container. The portlet itself may choose to cache content for any given response. The settings on this page apply only when the portlet itself does not specify a caching condition for a response.

    If you do not want any default caching for this portlet, choose Do Not Cache By Default. In this case, the wizard actually sets a cache duration of 0 seconds. As stated earlier, this cache setting only comes into play when the portlet itself does not specify a caching condition for a response.

    If you choose no caching here and you later decide to implement default caching for the portlet, then you can change the cache duration value in the portlet.xml file, which is generated by the wizard, to a number greater than zero.

    For more information, see Section 29.2.4, "Caching Style."

    Figure 31-8 The Caching Options Page

    Shows Caching page.
    Description of "Figure 31-8 The Caching Options Page"

  27. If you chose to cache the portlet, in the Default Expiry Conditions section, select:

    • Cache Content Expires After to expire the cached portlet content after a certain amount of time. Specify the time limit in the adjacent field.

    • Cache Content Never Expires to never expire the cached portlet content. You may want to select this option if the portlet contains static content that is unlikely to change.

  28. Click Next.

  29. On the Initialization Parameters page (Figure 31-9), click New to add an initialization parameter to the portlet.

    This adds a new row to the table of parameters. Double-click each field in the row to provide a name, default value and description for the parameter.

    Repeat this step to add more initialization parameters. When you are done, click Next.

    Initialization parameters provide the application developer, who decides what goes into the .war file, an alternative to JNDI variables for configuring the behavior of all of the different components of the application (for example, servlets and portlets) in a compatible way. These initialization parameters are added to the portlet.xml file.

    Figure 31-9 The Initialization Parameters Page

    Shows Initialization Parameters page.
    Description of "Figure 31-9 The Initialization Parameters Page"

  30. On the Portlet Navigation Parameters page (Figure 31-10), click Add to add a navigation parameter to the portlet.

    This adds a new row to the table of parameters. Double-click each field in the row to provide a name, label and hint for the parameter.

    Repeat this step to add more navigation parameters. When you are done, click Finish.

    Navigation parameters enable a portlet to communicate with the page on which it resides and with other portlets on that page. For more information, see Section 32.1.2, "How to Implement Navigational Parameters (WSRP 2.0)" and Section 34.7, "Contextually Linking WSRP 2.0 Portlets."

    Figure 31-10 The Portlet Navigation Parameters Page

    Description of Figure 31-10 follows
    Description of "Figure 31-10 The Portlet Navigation Parameters Page"

31.2.2 What Happens When You Create a JSR 168 Java Portlet Using the JDeveloper Wizard

When you use the JDeveloper wizard to create a JSR 168 Java portlet, JDeveloper generates a default implementation of the portlet. Specifically, the following files are created:

  • Two Java classes:

    • portletName.java is invoked by the portlet container and contains all the methods required by the portlet standards.

    • portletnameBundle.java contains all the translation strings for the portlet.

  • oracle-portlet.xml is generated if you selected the Oracle WSRP V2 extensions option.

  • portlet.xml is the portlet deployment file for the application.

  • web.xml is the web deployment file for the application.

  • Files for each portlet mode you selected for the portlet:

    • If you selected Generate JSP for the portlet mode, a JSP page is created for the mode, for example, view.jsp.

    • If you selected Generate ADF-Faces JSPX, a JSPX page is created for the mode, for example, view.jspx. You can add Faces components to this page.

    • If you selected Map to Path, no additional files are created as the code for the portlet mode resides in an existing resource. Code is added to the portlet's Java class to route requests to the specified target.

    • If you selected Custom Code, no additional files are created, but the code for the portlet mode resides in the portlet's Java class.

You can see all these files in the Application Navigator, as shown in Figure 31-11.

Figure 31-11 Files Generated for a JSR 168 Java Portlet

Shows contents of the Applications - Navigator.
Description of "Figure 31-11 Files Generated for a JSR 168 Java Portlet"

The next step is to extend the sample code with your own business logic to implement the desired functionality and features for your portlet. For more information, see the JSR 168 at:

http://www.jcp.org/en/jsr/detail?id=168

For a specific example, see "Step 3: Create the Business Logic for the Standards-Based Portlet" in the Oracle Fusion Middleware Tutorial for Oracle WebCenter Developers.

31.2.3 How to Create a PDK-Java Portlet

Using the Create Oracle PDK-Java Portlet wizard in JDeveloper you can quickly and easily create PDK-Java portlets. You can choose which portlet modes you want to implement and the implementation method (JSP, HTTP servlet, Java class, or HTML) to use for each mode. The wizard then creates a simple implementation for each of the selected modes.

To create a PDK-Java portlet using the JDeveloper wizard:

  1. In the JDeveloper Application Navigator, open the application under which you want to create your portlet.

    The application must be scoped for portlet creation. An easy way to achieve this is to use a Portlet Producer Application. WebCenter Applications are not scoped for portlet creation.

  2. Right-click the project under which you want to create your portlet, and choose New.

    Note:

    To create the portlet in an existing producer, right-click the producer's provider.xml file and choose Add Portlet. This takes you directly to the General Portlet Information page of the Create Oracle PDK-Java Portlet wizard (step 8).
  3. In the New Gallery, expand Web Tier, select Portlets and then Oracle PDK-Java Portlet, and click OK.

    Note:

    Selecting Oracle PDK-Java Portlet opens the wizard for creating PDK-Java portlets. Selecting Standards-based Java Portlet opens the wizard for creating JSR 168-compliant portlets.
  4. On the Provider Details page of the Create Oracle PDK-Java Portlet wizard (Figure 31-12), enter a name for the new producer to contain your portlet. This name must be unique within the project.

    In the PDK-Java, the term provider is used instead of producer. A provider is the same thing as a producer.

    Figure 31-12 The Provider Details Page

    Shows Provider Description page.
    Description of "Figure 31-12 The Provider Details Page"

  5. Select Generate Deployment Properties File.

    This automatically generates two .properties files:

    • serviceID.properties defines properties for a producer with that service ID. The service ID has the same value as the producer name.

    • _default.properties is a default properties file. A producer application may have multiple producers, each with its own service ID. On registration, if no service ID is defined, then the default properties file is used.

  6. Select Generate XML Entries.

    This automatically generates a producer definition file (provider.xml) for the producer that contains details of the portlets belonging to the producer, including those generated by the wizard.

  7. Select Generate Index JSP and then click Next.

    This automatically generates an index.jsp file that lists all the producers that reside in the application with hyperlinks that enable easy access to producer test pages.

  8. On the General Portlet Information page (Figure 31-13), enter a name and display name for your portlet.

    The name is used internally and is not exposed to users. The display name is displayed to users in portlet selection lists, such as the Component Palette.

    The description is not implemented in custom WebCenter applications so you do not need to enter a value in this field unless your portlet is likely to be consumed by other applications, such as Oracle Portal.

    Figure 31-13 The General Portlet Information Page

    Shows Portlet Description page.
    Description of "Figure 31-13 The General Portlet Information Page"

  9. In the Timeout Interval (Seconds) field, enter the number of seconds to allow for rendering the portlet.

  10. In the Timeout Message field, enter a message to display if the rendering of the portlet exceeds the timeout interval specified and then click Next.

  11. On the View Modes page (Figure 31-14), under Show Page, from the Implementation Style dropdown list, select the implementation style to use for the portlet's Shared Screen mode.

    • Select JSP to implement the portlet's Shared Screen mode as a JavaServer Page. In the File Name field, enter the name of the file to be generated by the wizard.

    • Select HTTP Servlet to implement the portlet's Shared Screen mode as an HTTP servlet. In the Package Name field, enter the name of the package that contains the HTTP servlet. In the Class Name field, enter the Java class to be referenced with the portlet's Shared Screen mode.

    • Select HTML File to implement the portlet's Shared Screen mode as an HTML file. In the File Name field, enter the name of the file to be generated by the wizard. Note that, when you choose HTML File, the following code is added inside the <renderer> element of your provider.xml file:

      <showPage class="oracle.portal.provider.v2.render.http.ResourceRenderer">
          <resourcePath>provider_id/portlet_name/file.html</resourcePath>
          <contentType>content_type</contentType>
          <charSet>char_set</charSet>
       </showPage>
      

      charSet indicates the character set that the producer must use to encode the HTML page. The default character set is determined by JDeveloper preferences. If you require a different character set, you must update this element of provider.xml accordingly.

    • Select Java Class to implement the portlet's Shared Screen mode as a Java class. In the Package Name field, enter the name of the package that contains the Java class. In the Class Name field, enter the name of the Java class.

    For more information about Shared Screen mode, see Section 31.2.5.1.1, "Shared Screen Mode (View Mode for JSR 168)."

    Figure 31-14 The View Modes Page

    Shows Show Modes page.
    Description of "Figure 31-14 The View Modes Page"

  12. To implement Full Screen mode for your portlet, select Show Details Page and then select an implementation style as described for Full Screen mode in step 11.

    For more information about Full Screen mode, see Section 31.2.5.1.5, "Full Screen Mode (PDK-Java)."

  13. At this point in the wizard, you can click Finish to create the portlet immediately, using the default values for all remaining settings.

    To provide additional details for your portlet, click Next and follow the remaining steps.

  14. On the Customize Modes page (Figure 31-15), Edit Page is selected by default. To implement Edit mode for your portlet, select an implementation style as described for Shared Screen mode in step 11. If you do not want to implement Edit mode, then deselect Edit Page.

    For more information about Edit mode, see Section 31.2.5.1.2, "Edit Mode (JSR 168 and PDK-Java)."

    Figure 31-15 The Customize Modes Page

    Shows Customize Modes page.
    Description of "Figure 31-15 The Customize Modes Page"

  15. To implement Edit Defaults mode for your portlet, select Edit Defaults Page, and then select an implementation style as described for Shared Screen mode in step 11.

    For more information about Edit Defaults mode, see Section 31.2.5.1.3, "Edit Defaults Mode (JSR 168 and PDK-Java)."

  16. Click Next.

  17. On the Additional Modes page (Figure 31-16), to implement Help mode for your portlet, select Help Page, and then select an implementation style as described for Shared Screen mode in step 11.

    For more information about Help mode, see Section 31.2.5.1.6, "Help Mode (JSR 168 and PDK-Java)."

    Figure 31-16 The Additional Modes Page

    Shows Additional Modes page.
    Description of "Figure 31-16 The Additional Modes Page"

  18. To implement About mode for your portlet, select About Page, and then select an implementation style as described for Shared Screen mode in step 11.

    For more information about About mode, see Section 31.2.5.1.7, "About Mode (JSR 168 and PDK-Java)."

  19. Click Next.

  20. On the Public Portlet Parameters page (Figure 31-17), click Add to add a public parameter to your portlet.

    This adds a new row to the table of parameters. Double-click each field in the row to provide a name, display name, and description for the parameter.

    Repeat this step to add more public parameters. When you are done, click Next.

    Public portlet parameters enable a portlet to communicate with the page on which it resides and with other portlets on that page. For more information, see Section 32.2.2, "How to Implement Public Parameters."

    Figure 31-17 The Public Portlet Parameters Page

    Shows Public Portlet Parameters page.
    Description of "Figure 31-17 The Public Portlet Parameters Page"

  21. Oracle PDK-Java events are not supported in custom WebCenter applications, so On the Public Portlets Events page, click Finish.

    For more information about events, see the Oracle Fusion Middleware Developer's Guide for Oracle Portal.

31.2.4 What Happens When You Create a PDK-Java Portlet

When you use the JDeveloper wizard to create a PDK-Java portlet, JDeveloper generates a default implementation of the portlet. Specifically, the following files are created:

  • Files for each portlet mode you selected, for example portletnameEditPage.jsp.

  • provider.xml is the producer definition file that contains details of the portlets belonging to the producer.

  • web.xml is the web deployment file for the application.

  • weblogic.xml includes a shared library definition pointing to the PDK-Java shared library.

  • index.jsp is used by JDeveloper for testing purposes.

  • _default.properties is the default properties file.

  • serviceID.properties is the properties file for the producer identified by serviceID.

All these files are required to deploy and run the portlet successfully, except for index.jsp.

You can see all these files in the Application Navigator, as shown in Figure 31-18.

Figure 31-18 Files Generated for a PDK-Java Portlet

Shows contents of Applications - Navigator.
Description of "Figure 31-18 Files Generated for a PDK-Java Portlet"

The next step is to extend the sample code with your own business logic to implement the desired functionality and features for your portlet. For more information, see the PDK-Java JavaDoc.

31.2.5 What You May Need to Know When Creating Java Portlets

When you write your portlets in Java for either JSR 168 or PDK-Java, you should follow the best practices described in this section.

This section includes the following subsections:

31.2.5.1 Guidelines for Portlet Modes

Portlet mode exhibits the runtime portlet functionality seen by users. You can provide an extended set of modes in addition to the standard ones provided with Oracle WebCenter and Oracle Portal. Different portal products support extended portlet modes as follows:

  • Oracle WebCenter and Portal have defined an extended set of modes that these two products support. Different modes are available for both PDK-Java and JSR 168 portlets. PDK-Java offers some modes not offered by JSR 168. If you are coding portlets to JSR 168, then you can declare custom portlet modes in the portlet.xml file 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 JSR 168 portlets includes a custom mode called 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. You can offer any of these modes to users. In fact, it is recommended that some modes like Edit Defaults are offered.

  • Third party portal products may have their own set of extended modes (JSR 168 custom modes) that producers can offer. In custom WebCenter applications and Oracle Portal, chrome UI for portlets only shows the custom modes that are defined in Oracle WebCenter Framework. Arbitrary custom modes that a third party or custom portlet producer offers are ignored and therefore not supported.

This section includes the following subsections that discuss each of the standard portlet modes:

31.2.5.1.1 Shared Screen Mode (View Mode for JSR 168)

A portlet uses Shared Screen mode (known as View mode in JSR 168) to appear on a page with other portlets. This is the mode most people think about when they envision a portlet. A JSR 168 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 shares the page. For example, suppose you choose to place your portlet inside of an HTML table cell. The portlet should display only content that can be rendered within a table cell. Furthermore, the actual size of the table cell may vary depending on user settings, the browser width, and the amount and style of content in the portlet.

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, tables, if 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.org/MarkUp/).

  • 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 and HTML Tidy can help detect and fix hanging and unnecessary tags.

  • Consider restrictions imposed by container objects: If your portlet is contained inside of an HTML element, such as a table cell, then you must ensure that your portlet can be rendered within that container. For example, if you place a portlet in a table cell, then you could not use frames in the portlet because they 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 may 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 has on a user's page. If your portlet requires more room than given, then 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 portlet's 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 want and they can change it at any time. Your portlet should handle these situations gracefully.

The HTML you use also affects 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 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, then it can greatly slow the rendering of the page.

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 page. The portlets access these settings for their fonts and colors, either directly or using the Application Programming Interface (API).

While different browsers have implemented varying levels of the full CSS specification, Oracle WebCenter Framework 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, then your portlet may look out of place when the user changes the page style settings. Since you have no way of knowing the user's font and color preference choices, you might also choose to hard code a font color that turns out to be the same as the user's chosen background color, in which case your portlet appears to be invisible to that user.

  • Use the CSS APIs to format your text: The style sheet definition is available at the top of pages, but you should not call it directly. Instead, use the APIs provided to format your text appropriately. This method ensures that your portlets work even if the style sheet changes in the future.

  • Avoid using CSS for absolute positioning: Since users can personalize their pages, you cannot guarantee that your portlet can appear in a particular spot.

  • Follow Accessibility Standards: You should ensure that you code your style sheets according to existing accessibility standards (more information available at http://www.w3.org/TR/WCAG10-CSS-TECHS/).

31.2.5.1.2 Edit Mode (JSR 168 and PDK-Java)

A portlet uses Edit mode to enable users to personalize the behavior of the portlet. Edit mode provides a list of settings that the user can change. These settings may include the title, type of content, formatting, amount of information, defaults for form elements, and anything that affects the appearance or content of the portlet.

Users typically access a portlet's Edit mode by choosing Personalize from the portlet's dropdown list of options. When users choose Personalize, a new page appears in the same browser window. The portlet typically creates a web page representing a dialog to choose the portlet's settings. After applying the settings, users automatically return to the original page.

Guidelines for Edit Mode Operations

The following guidelines should govern what you expose to users in Edit mode:

  • Enable users to personalize the title of the portlet: The same portlet may be added to the same page several times. Enabling the user to personalize the title helps alleviate confusion.

  • If using caching, invalidate the content: If personalizations cause a change in portlet display or content, then you must ensure that the portlet content is regenerated and not returned from the cache. Otherwise, the user may see incorrect content.

  • Do not use Edit mode as an administrative tool: Edit mode is meant to give users a way of changing the behavior of their portlets. If you want to change producer settings or do other administrative tasks, then you should create secured portlets specifically for those tasks.

Guidelines for Buttons in Edit Mode

For consistency and user convenience, Edit mode should implement the following buttons in the following order:

  • OK saves the user personalizations and returns the portlet to view mode.

  • Apply saves the user personalizations and reloads the current page.

  • Cancel returns the portlet to view mode without saving changes.

Guidelines for Rendering Personalization Values

When you show the forms used to change personalization settings, you should default the values such that the user does not have to constantly reenter settings. When rendering the personalization values, use the following sequence to provide consistent behavior:

  1. User preference: Query and display this user's personalizations, if available.

  2. Instance defaults: If no user personalizations are found, then query and display system defaults for the portlet instance. These are set in Edit Defaults mode and apply only to this portlet instance.

  3. Portlet defaults: If no system default personalizations are found, then display general portlet defaults, which may be blank. General portlet defaults are sometimes hard coded into the portlet but should be overridden if either of the two previous conditions apply.

This logic enables the personalizations to be presented in a predictable way, consistent with the other portlets in the custom WebCenter application.

31.2.5.1.3 Edit Defaults Mode (JSR 168 and PDK-Java)

A portlet uses the Edit Defaults mode to enable administrators to customize the default behavior of a particular portlet instance. Edit Defaults mode provides a list of settings that the application developer can change. These settings may include the title, type of content, formatting, amount of information, defaults for form elements, and anything that affects the appearance or content of the portlet.

These default personalization settings can change the appearance and content of that individual portlet for all users. Because Edit Defaults mode defines the system-level defaults for what a portlet displays and how it displays it, this mode should not be used as an administrative tool or for managing other portlets.

Administrators access Edit Defaults mode, when editing a page, by choosing Customize from the portlet's dropdown list.

When users click the Customize icon, the portlet displays in the same browser window. The portlet typically creates a web page representing a dialog to personalize the portlet instance settings. After applying the settings, users are automatically returned to the original page.

Guideline for Edit Defaults Mode Options

The following guideline should govern what you expose to page designers in Edit Defaults mode:

  • Do not use Edit Defaults mode as an administrative tool. Edit Defaults mode gives users a way of changing the behavior of their portlets. If you want to change producer settings or do other administrative tasks, then you should create secured portlets specifically for those tasks.

Guidelines for Buttons in Edit Defaults Mode

For consistency and user convenience, Edit Defaults mode should implement the following buttons in the following order:

  • OK saves the user personalizations and returns the portlet to view mode.

  • Apply saves the user personalizations and reloads the current page.

  • Cancel returns the portlet to view mode without saving changes.

Guidelines for Rendering Personalization Values

When you show the forms used to change personalization settings, you should default the values so that the application developer does not have to constantly reenter settings. When rendering personalization values, use the following sequence to provide consistent behavior:

  1. Instance preferences: Query and display system defaults for the portlet instance.

  2. Portlet defaults: If no system default personalizations are found, then display general portlet defaults, which may be blank. General portlet defaults are sometimes hard coded into the portlet but should be overridden by system defaults.

This logic enables the personalizations to be presented in a predictable way, consistent with the other portlets in the custom WebCenter application.

31.2.5.1.4 Preview Mode (JSR 168 and PDK-Java)

A portlet uses Preview mode to show the user how the portlet looks before adding it to a page. Preview mode visually represents what the portlet can do. Not all portlet consumers call this mode. For example, Oracle Portal uses this mode but Oracle WebCenter Framework does not.

Note:

Oracle Portal calls this mode when the user clicks the Preview icon on the Add Portlet page. A window then displays the preview of the chosen portlet. The user has the option to add that portlet to the page. This mode has no particular application in custom WebCenter applications, but used in Oracle Portal's Portlet Repository.

Guidelines for Preview Mode

The following guidelines should govern what you expose to users in Preview mode:

  • Provide an idea of what the portlet does. Preview mode should generate enough content for the user to get an idea of the actual content and functionality of the portlet.

  • Keep your portlet previews small. The amount of data produced in this mode should not exceed a few lines of HTML or a screen shot. Preview mode appears in a small area, and exceeding the window's size looks unprofessional and forces users to scroll.

  • Do not use live hyperlinks. Links may not work as expected when rendered in Preview mode. Hyperlinks can be simulated using the underline font.

  • Do not use active form buttons. Forms may not work as you expect them to when rendered in Preview mode. If you decide to render form elements, then do not link them to anything.

31.2.5.1.5 Full Screen Mode (PDK-Java)

Portlets use Full Screen mode to provide a larger version of the portlet for displaying additional details. Full Screen mode lets a portlet have the entire window to itself. Not all portlet consumers call this mode. For example, Oracle Portal uses this mode but Oracle WebCenter Framework does not. In Oracle Portal, users access a portlet's Full Screen mode by clicking the title of the portlet.

For example, if a portlet displays expense information, then it could show a summary of the top ten spenders in Shared Screen mode and the spending totals for everyone in Full Screen mode. Portlets can also provide a shortcut to web applications. If a portlet provided an interface to submitting receipts for expenses in Shared Screen mode, then it could link to the entire expense application from Full Screen mode.

Technically, JSR 168 portlets do not have Full Screen mode. However, you can implement the equivalent of Full Screen mode for a JSR 168 portlet with View mode (Shared Screen mode) and a maximized state for the window.

31.2.5.1.6 Help Mode (JSR 168 and PDK-Java)

A portlet uses Help mode to display information about the functionality of the portlet and how to use it. The user should be able to find useful information about the portlet, its content, and its capabilities with this mode.

Users access a portlet's Help mode by choosing the Help action in the portlet.

Guideline for Help Mode

The following guideline should govern what you expose to users in Help mode:

  • Describe how to use the portlet. Users may not know all the features your portlet provides just from its interface. Describe the features and how to get the most out of them.

31.2.5.1.7 About Mode (JSR 168 and PDK-Java)

Users must be able to see what version of the portlet is currently running, its publication and copyright information, and how to contact the author. Portlets that require registration may link to web-based applications or contact information from this mode, as well.

Users access a portlet's About mode by choosing About from the dropdown list in the portlet's chrome. A new page appears in the same browser window. The portlet can either generate the content for this new page or take the user to an existing page or application.

Guideline for About Mode

The following guideline should govern what you expose to users in About mode:

  • Display relevant copyright, version, and author information. Users want to know what portlet they are using and where they can get more information. The about page may become important when supporting your portlets.

31.2.5.2 Guidelines for Navigation within a Portlet

In some ways, navigation between different sections or pages of a single portlet is identical to navigation between standard web pages. Users can submit forms and click links. In typical, simple web pages, both of these actions involve sending a message directly to the server responsible for rendering the new content, which is then returned to the client. In portlets, which comprise only part of a page, the form submission or link rendered within the portlet does not directly target the portlet. It passes information to the portlet through the custom WebCenter application. If a link or form within a portlet does not refer back to the application, then following that link takes the user away from the application, which is not typically the desired behavior.

The component developer does not need to know the detailed mechanics of how the parameters of a form or link get passed around between the user, application, and portlet. However, they must understand that they cannot write links in a portlet the same way they do for typical, simple web pages.

Types of Links for Portlets

A portlet may render links of four classes, as follows:

  • Intraportlet links require the portlet to be aware of the address of the custom WebCenter application because they actually refer to it in some way.

  • Application links, like intraportlet links, must be aware of the address of the custom WebCenter application for the same reason.

  • External links make no reference to the custom WebCenter application and work in portlets as they would do in a normal web page.

  • Internal/Resource links, like external links, also make no reference to the custom WebCenter application.

Figure 31-19 contains a summary of these link types. The arrows indicate how the links reference the resources to which they logically refer.

Figure 31-19 Custom WebCenter Application Link Types

Description of Figure 31-19 follows
Description of "Figure 31-19 Custom WebCenter Application Link Types"

This section includes the following subsections:

31.2.5.2.1 Intraportlet Links

Intraportlet links go to different sections or pages within a given portlet. Strictly speaking, they refer to the page containing the portlet, but they contain parameters that cause the portlet to render a different section or page within that page when it is requested by the user.

As a direct consequence, a portlet cannot expect to render links to different sections or pages of itself using relative links or absolute links based on its own server context. Intraportlet link are useful for intraportlet navigation, either as links or form submission targets.

31.2.5.2.2 Application Links

Application links refer to significant pages within the custom WebCenter application, such as the user's home page.

31.2.5.2.3 External Links

External links refer neither to the portlet (through a page) nor to any part of the custom WebCenter application. If selected, these links take the user away from the application, for example, www.oracle.com.

31.2.5.2.4 Internal/Resource Links

Internal/Resource links refer to internal (to the portlet) resources. Sometimes they are exclusively used internally during portlet rendering, for example as a server side include. On other occasions, they may be used externally to reference portlet resources like images. In this latter case, you can use the PDK-Java constructResourceURL method in the UrlUtils class to retrieve images from behind a firewall using resource proxy. Note that in order for resource proxying to work, you must first set the JNDI variable, oracle/portal/provider/sample/resourceUrlKey, for the producer. For more information about setting JNDI variables, see Section 32.2.4.2, "Setting JNDI Variable Values."

For example, lottery.jsp of the lottery sample, which is available with PDK-Java, contains resource proxy requests for images.

<%@ page contentType="text/html;charset=UTF-8" %>
<%@ page session="false" import="oracle.portal.provider.v2.render.*" %>
<%@ page import="oracle.portal.provider.v2.render.http.HttpPortletRendererUtil" %>
<%@ page import="oracle.portal.provider.v2.url.UrlUtils" %>
<%@ page import="oracle.portal.sample.v2.devguide.lottery.*" %>
<%
  LottoPicker picker = new LottoPicker();
  picker.setIdentity(request.getRemoteAddr() ); %>
<% PortletRenderRequest portletRequest = (PortletRenderRequest)
request.getAttribute("oracle.portal.PortletRenderRequest"); %>
<% String name = portletRequest.getUser().getName(); %>
<P class="PortletHeading1" ALIGN="CENTER">Hi <%= name %>, Your Specially
  Picked</P><P ALIGN="CENTER"><IMG SRC="<%= UrlUtils.constructResourceURL(portletRequest,
  HttpPortletRendererUtil.absoluteLink(request, "images/winningnumbers.gif")) %>"
  WIDTH="450" HEIGHT="69" ALIGN="BOTTOM" BORDER="0"></P>
<P>
<P ALIGN="CENTER">
<TABLE ALIGN="CENTER" BORDER="0" CELLPADDING="0" CELLSPACING="0">
<TR>
<% 
     int [] picks = picker.getPicks();
     for (int i = 0; i < picks.length; i++) { 
%>
             <TD>
    <IMG SRC="<%= UrlUtils.constructResourceURL(portletRequest,
      HttpPortletRendererUtil.absoluteLink(request, "images/ball" + picks[i])) %>
      .gif" WIDTH="68" HEIGHT="76" ALIGN="BOTTOM" BORDER="0">
     </TD>
<%
     }

For session-based producers, any cookies returned from the original initSession call to the producer are sent with the request back to the producer to maintain the right session context.

31.2.5.3 Guidelines for JavaScript

JavaScript can often be 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 want to direct users elsewhere, then 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 JavaScript on the page.

31.2.5.4 Guidelines for PDK-Java Portlets

In Oracle WebCenter Framework, PDK-Java portlets work somewhat differently than they did in Oracle Portal. As a result, you must be aware of the following new design considerations when you build PDK-Java portlets in Oracle WebCenter Framework:

  • Your portlet must not contain any code that relies upon the URL format or parameters in the request that were not explicitly added by your portlet.

  • You should never assume that your portlet is the only one on a page, regardless of the portlet mode. For example, even if your are in Edit mode, you should not assume that yours is the only portlet on the page.

  • Never write a portlet mode that simply redirects. A redirect can only be issued while processing a post to your portlet or following a link generated by your portlet.