Creating portlet projects (JSR 168)
You can create and maintain resources for portlet applications using the JSR 168 portlet API in a Portlet Project (JSR 168). Portlet projects can be added to a new or existing enterprise application project. For more details on creating a Faces portlet project that uses the JSR 168 portlet API, see Creating Faces portlet projects.
The following limitations exist for JSR 168 portlet projects:
- Struts portlets are not available for JSR 168 portlets.
- Some JSR 168 portlet API custom tags (<namespace>, <actionURL>, etc.) cannot be used within the <view> tag of a Faces portlet JSP file. Snippets from Snippets view for Faces portlet JSP files need to be inserted after the <view> tag.
- Changing the portlet mode using the 'portletMode' attribute of <actionURL> causes the Faces portlet to fail to store data and invoke an action. As an alternative, use ActionResponse#setPortletMode() in the Faces action to change the portlet mode
To create a new JSR 168 portlet project,...
- Select File > New > Project. Then, select the Portlet Project (JSR 168) option on the right, and then click the Next button. The New Portlet Project wizard opens.
- 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.
- 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.
Note: By default, the target server is WebSphere Portal v5.0. The portlets created for WebSphere Portal v5.0 will run on a WebSphere Portal v5.1 server, but if you want to use the additional functions provided by WebSphere Portal v5.1 in your portlet, click Show Advanced >>, and select WebSphere Portal v5.1 as the Target server. Supply any of the following values:
- 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.
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 JSR 168 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.
- 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 GenericPortlet 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.
- 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 InfoCenter (see WebSphere Portal Product Documentation).
- Click Next.
- Update or add any general portlet settings in the Portlet Settings page, and click Next. (See Creating portlet projects (IBM API) for more details on these options.) For creation of an Empty portlet, when you click Next, you will skip immediately to the Miscellaneous page of the wizard. 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 JSR 168 portlet projects.
- In the Action and Preferences page, define the action and preferences handling of the portlet.
- Add action request handler
- This option implements the processAction method for handling action requests. The action request handler is invoked when an HTTP request associated with a portlet action is received.
- Add form sample
- This option adds a form sample in the view panel.
- Add preferences handling
- This option shows preferences on the view panel. It also provides an edit panel to modify portlet preferences. Portlet preferences are stored as persistent data and may be used for personalized preferences.
- Add preferences validator
- This option adds a preferences validator class to validate preferences.
- Click Next.
- If you selected WebSphere Portal v5.1 as the target server earlier, you can 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.
Click Next.
- 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.
- 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.
- The wizard will generate a portlet project using an IBM extension: wps.markup, which will allow the portlet further markup distinctions that extend beyond the pure MIME type. For more information about this IBM extension, refer to Developing portlets using JSR 168 and WebSphere Portal V5.02.
- The view mode is always selected.
- The edit mode is automatically added to the generated portlet if the Add preferences handling option was selected in the Action and Preferences page.
- Click Finish to create the new portlet project.
- 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.
- Some of the portlet configuration parameters are assigned default values. To reconfigure these values by editing the portlet deployment descriptor, refer to Customizing JSR 168 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 portlets. To add portlet JSP files, refer to Creating portlet JSP files.
Related concepts
Creating portlets and portlet projects
Working with portlet deployment descriptors
Markup languages
Related tasks
Customizing JSR 168 portlets
Creating portlets
Creating portlet JSP files
Customizing empty JSR 168 portlet projects