Creating portlet projects (IBM API)

You can create and maintain the resources for your portlet applications in portlet projects. Portlet projects can be added to a new or existing enterprise application project.

Refer to the following topics for additional details about creating specialized portlets:
Portlet applications developed for WebSphere® Portal 5.0 or 5.1 are not supported on WebSphere Portal 4.2. Rational® Developer does support portlet project migration from WebSphere Portal 4.2 to WebSphere Portal 5.x. Please refer to the Rational Developer Migration Guide for a detailed description of the portlet project migration process.
Note: A WebSphere Portal 5.0 portlet should not require migration to WebSphere Portal 5.1 to run. However, you review the information in Migrating WebSphere Portal v5.0 portlets to v5.1.

To create a new portlet project, follow these steps:

  1. Select File > New > Project. Then, select the Portlet Project option on the right, and then click the Next button. The New Portlet Project wizard opens.
  2. Provide values, as appropriate, for the following fields:
    Project name
    Name for the new portlet project.
    Project location
    The location in the file system where the project will be created. You can change the file system location by using Browse.
    WebSphere Portal version
    Select the appropriate WebSphere Portal version for your portlet project. Your selection will set the appropriate servlet and corresponding target server for your development environment.
    Create a portlet
    If you do not want to create the initial portlet definitions in the project, clear this check box. Typically, you do not need to create a portlet when you import a portlet WAR file into the project.
    To set the project's J2EE settings, or to specify the target run-time server for the project, click the Show Advanced >> button, and supply any of the following values:
    Note: By selecting a WebSphere Portal version value above, both Servlet version and Target server are set to the appropriate values. Editing these two fields is not recommended.
    Servlet version
    Specifies the version of the Servlet and JSP specifications to be included in your portlet application. Version 2.3, the default, includes a Servlet Specification level of 2.3 and a JSP Specification level of 1.2. This default should be used to create portlet projects targeted for WebSphere Portal 5.0 or 5.1 servers.

    Use the 2.2 servlet version when you are creating an Empty portlet project that you intend to import a WebSphere Portal 4.x portlet WAR file into. Version 2.2 includes a Servlet Specification level of 2.2 and a JSP Specification level of 1.1. Features such as Servlet Filters and Life Cycle Event Listeners cannot be used if this level is chosen.

    Note that the servlet version will determine the choice of target servers that appear in the drop-down list.

    Target server
    Select the version of WebSphere Portal that your portlet application will be installed to (either WebSphere Portal v5.0 or v5.1).
    Note: Ensure that you do not accidentally select one of the WebSphere Application Server options.
    Add module to an EAR project
    Deselect this check box only if you do not intend to deploy the portlet.
    EAR project
    Name of an enterprise application project (EAR project) that the portlet project should be associated with for purposes of deployment. The information used to deploy the portlet project to WebSphere Portal in the test environment will be added in this project. All portlet applications associated with a single EAR project will run on a single session at the test environment. You may separate portlet applications into multiple EAR projects. You should use the same EAR project for other projects that are related.
    Context root
    A context root for the portlet project. It is used as the top-level directory of your portlet application when it is deployed to WebSphere Portal in the test environment. It must not be same as the ones used by other projects.
    Add support for annotated Java™ classes
    Ensure that this check box is selected if you plan on using model annotations to generate code in your project.

    If you want accept the defaults associated with a Basic IBM® API portlet project, click Finish. If you prefer to customize the project options, or want to create a project that is enabled for a different type of portlet, click Next.

  3. Select the portlet type that is appropriate for the portlet project. For more information about portlet types, refer to Creating portlets and portlet projects.
    Empty portlet
    Creates a portlet application that extends the PortletAdapter class, with minimum code included. Refer to Customizing empty portlet projects if you create a new portlet application from scratch.
    Basic portlet
    Creates a basic portlet application which extends the PortletAdapter class. This is a complete application with a concrete portlet and a concrete portlet application. It contains a portlet class that extends the PortletAdapter class, sample JSP files that are used in rendering the portlet, and a sample Java bean. In addition to these basic resources, you can add sample code to the project for functions that are often used by portlet applications as you specify additional wizard options.
    Faces portlet
    Creates a Faces portlet application. For more details, refer to Creating Faces portlet projects.
    Struts portlet
    Creates a Struts portlet application. For more details, refer to Creating Struts portlet projects.
  4. Click Next.
  5. Select one or more of the Web Project features, as necessary. Deselect the Web Diagram check box if you are creating Basic or Empty portlet. For more information how WebSphere Portal supports the use of tags from the JSP Standard Tag Library (JSTL), refer to the "Using JSTL tags in the portal JSPs" in the WebSphere Portal Information Center (see WebSphere Portal Product Documentation).
  6. Click Next.
  7. Update or add any general portlet settings in the Portlet Settings page:
    Application name
    Name of the portlet application. It is used to manage the portlet application by the portal administrator. To update this in the future, use the portlet deployment descriptor editor and update the Display name of each concrete portlet application.
    Portlet name
    Name of the portlet. It is used, by the portal administrator, to manage the portlet(s). To update this in the future, use the portlet deployment descriptor editor and update the Display name of each concrete portlet.
    Default locale
    Select the default locale that is used if the client locale cannot be determined. To add more locales to be supported, use the portlet deployment descriptor editor to add Locale in every concrete portlet.
    Portlet title
    Portlet title for the default locale. This title appears on the portlet title bar. To update this in the future, use the portlet deployment descriptor editor and update the Title of each concrete portlet.
    Change code generation options
    Select this to change the Package prefix and/or Class prefix.
    Package prefix
    The prefix of the Java package name.
    Class prefix
    The prefix of the Java class name.
  8. For creation of an Empty portlet, when you click Next, you will skip immediately to the Miscellaneous page of the wizard. To finish creating a Basic portlet, click Next. If you click Finish to create an empty portlet, the wizard will create an empty project container primed with the appropriate folder structure, along with a deployment descriptor. To complete the portlet application, you need to customize the new empty portlet project. See Customizing empty portlet projects.
  9. Optionally, add sample code for event handling that is often used by the portlet application in the new portlet project.
    Portlet action event
    An ActionEvent is sent to the portlet when an HTTP request is received that is associated with a portlet action.
    Add action listener
    To get a Java class which implements the ActionListener interface to handle the ActionEvent object.
    Add form sample
    To get a JSP file for the view mode including a form sample to handle the ActionEvent with Java classes.
    Cooperative portlets
    Cooperative portlets provide a model for declaring, publishing, and sharing information with each other using the WebSphere Portal property broker. For more information on the cooperative portlets, refer to "Cooperative portlets" in the WebSphere Portal Information Center. The cooperative portlets options are available only when the Servlet level option is 2.3 or higher in the initial page of the wizard. A cooperative portlet generated by the wizard can run on WebSphere Portal 5.x servers.
    Enable Click-to-Action target
    This adds a sample WSDL file so that the Click-to-Action target can receive input properties. If you select this option with the Add form sample option in the Portlet action event group in this panel, the generated portlet project will be enabled as a Click-to-Action receiver. Otherwise, you must create your own action handler and form, and then customize the WSDL file as you require.
    Add Click-to-Action sender portlet sample
    This adds a simple Click-to-Action sender portlet. This portlet is useful to test receiver function and can be used to reference sample JSP files of the Click-to-Action source (sender) portlet.
    Enable Click-to-Action source
    This adds the Click-to-Action tag library directive for JSP files of the Click-to-Action source portlet, so that it can publish their output properties. To change the Click-to-Action action to send, you should customize this JSP page to use the <c2a:encodeProperties> and <c2a:encodeProperty> tags.
    Portlet message event
    Message events can be sent from one portlet to others if the recipient portlets are placed on the same page as the sending portlet.
    Add message listener
    To get a Java class that implements the MessageListener interface to handle the MessageEvent object.
    Add message sender portlet sample
    To get two portlets. One is a message sender portlet and the other is a portlet to handle the message event.
    Event log viewer
    Add event log viewer
    To add a function showing events received by listeners in the view mode. To select this option, you need to add at least one of the event listeners
    Add edit panel to change maximum event count
    To support the edit mode. The PortletData object is used to save user persistent data, and a JSP file for the edit mode is added. In this edit mode, you can change the default maximum event count.
  10. Click Next.
  11. Add sample code to support credential vault handling in the Single Sign-On page. This allows users and administrators to safely store credentials for authentication. For more information on the credential vault handling, refer to "Portlet authentication" in the WebSphere Portal Information Center.
    Add credential vault handling
    Select this option to support credential vault handling. WebSphere Portal supports the use of a credential vault where users and administrators can safely store credentials for authentication. Portlets written to extract the user's credentials from the vault can hide the login challenge from the user. Select one of the following types of vault slots.
    Use portlet private credential vault slot
    A portlet private slot stores user credentials that are not shared among portlets.
    Use shared credential vault slot
    A shared slot stores user credentials that are shared among the user's portlets.
    Use administrative credential vault slot
    An administrative slot allows each user to store their confidential information for accessing administrator-defined resources (for example, Lotus Notes®).
    Use system credential vault slot
    A system slot stores system credentials where the actual confidential information is shared among all users and portlets.
    Slot name
    Defines the name of the credential vault slot to store and retrieve user credentials.
    Show password
    Select this option to show the password on the screen in the view mode.
  12. Click Next.
  13. In the Miscellaneous page, specify any additional markups and modes that you want to enable for the portlet in the project. The HTML markup, which must be supported by all portlet application, is always generated by the wizard. For more information on markup languages, refer to Markup languages.
    Add chtml markup support
    Add markup support for iMode mobile phone browsers.
    Add wml markup support
    Add markup support for WAP mobile phone browsers.
    Select portlet modes to be supported. The view mode will always be generated by the wizard. It must be supported by all portlet applications.
    Add edit mode
    Add support for the edit mode along with a sample edit panel. This option is disabled if you have selected either Add edit panel to change maximum edit count in the Event Handling panel or Add credential vault handling in the Single Sign-On panel. The edit mode will be added with these options.
    Add help mode
    Add support for the help mode along with a sample help panel.
    Add configure mode
    Add support for the configure mode along with a sample configure panel.
  14. Click Finish to create the new portlet project.
  15. Click Yes if the Confirm Perspective Switch dialog box is displayed. If you do not want to be prompted for this every time, select the Do not show this message again check box.
  16. Some of the portlet configuration parameters are assigned default values. To reconfigure these values by editing the portlet deployment descriptor, refer to Customizing IBM API portlets. Depending on your selection, sample portlet(s) with sample JSP files are generated. To add additional portlets to a portlet project, refer to Creating a Portlet. To add portlet JSP files, refer to Creating portlet JSP files.
Note: WS-I compliance warning messages will be displayed in the Problems view for Click-to-Action-enabled portlets. You can ignore them in the Click-to-Action WSDL resources. Alternatively, to prevent these warning messages from being displayed, you can change the compliance level on the WS-I compliance preferences:
  1. Select Window > Preferences > Workbench > Capabilities.
  2. Expand Web Service Developer, and ensure that Web Services Development is selected.
  3. Click Apply and then OK.
  4. Select Window > Preferences > Web Services > WS-I Compliance.
  5. Set the compliance levels to Ignore compliance, and then click Apply and OK.
Related concepts
Creating portlets and portlet projects
Working with portlet deployment descriptors
Markup languages
Developing cooperative portlets
Related tasks
Customizing IBM API portlets
Creating portlets
Creating portlet JSP files
Customizing empty portlet projects

(C) Copyright IBM Corporation 2002, 2005. All Rights Reserved.