JBoss.orgCommunity Documentation

JBoss Portlet Tools User Guide

Svetlana Mukhina

Thomas Heute

Version: 4.0.0


1. Introduction
1.1. What JBoss Portal and Portlet Tools are
1.2. Key Features of JBoss Portlet Tools
2. JBoss Portlet Tools Tasks
2.1. Creating and Deploying a Java Portlet
2.1.1. Creating a Web Project with JBoss Portlet Capabilities
2.1.2. Adding a Java Portlet to a Web Project
2.1.3. Deploying a Portlet to JBoss Portal
2.2. Creating and Deploying a JSF Portlet
2.2.1. Creating a JSF Project with JBoss Portlet Capabilities
2.2.2. Adding a JSF Portlet to the Project and Deploying It to JBoss Portal
2.3. Creating and Deploying a Seam Portlet
2.3.1. Creating a Seam Project with JBoss Portlet Capabilities
2.3.2. Adding a Seam Portlet to the Project and Deploying It to JBoss Portal
3. Reference
3.1. JBoss Portlet Descriptors
3.2. Wizards
3.2.1. Java Portlet Wizard
3.2.2. JSF/Seam Portlet Wizard
3.3. JBoss Portlet Preferences
4. Summary
4.1. Other Relevant Resources on the Topic

Starting from 3.0.0.Alpha1 version, the JBoss set of plugins includes tools for supporting JBoss Portal and JSR-186/JSR-286 portlets. Thus, this guide provides instructions on how to get started and manage JBoss Portlet Tools.

This chapter shows how to create a Dynamic Web Project, add a Java Portlet to it and deploy it to the JBoss Portal.

Follow the next procedure to create a Web project with JBoss Portlet capabilities pointed to the JBoss Portal runtime.

  1. Select FileNewDynamic Web Project if you are in the Web perspective or select FileNewOtherWebDynamic Web Project in any other perspective. This will display the New Dynamic Web Project wizard.


  2. Specify the name of the project.

  3. Click the New in the Target Runtime area to create a JBoss Portal runtime. Choose JBoss Community > JBoss 4.2 Runtime and select the Create a new local server check box below. Click the Next button.


  4. The New Server Runtime Environment wizard appears. In the Name field, type JBoss Portal 2.7 Runtime, and then use the Browse button to point to the location of JBoss Portal + JBoss AS extracted. Click Next button to proceed.


  5. At this point a new JBoss Server instance will be created. On the next page you can verify the runtime information and configuration. If something is incorrect, press the Back button to return to the previous wizard page. Click the Finish button.


  6. Click the Modify button in the Configuration area to enable a portlet facet for the project.


  7. In the Project Facets dialog, check JBoss Core Portlet and click the OK button.


  8. The Java and Web Module pages are for configuring Java and Web modules in the project. Here the default values are fine, so leave everything as it is.

  9. The last wizard page will ask you to add JBoss Portlet capabilities to the project. Select Portlet Target Runtime Provider and click the Finish button to complete the project creation.


As the result, JBoss Portlet Tools adds JBoss Core Portlet facet to the project, creates an empty portlet.xml file and adds the JBoss Portlet library to the project classpath.


This chapter will explain how you can configure a JSF portlet within a JSF project with JBoss Portlet capabilities and then deploy it to JBoss Portal.

You can create a JSF project with JBoss Portlet capabilities in two ways:

Refer to the further sections for the procedures on how to do this.

The basic steps to create a dynamic Web project with the JBoss Portlet capabilities are as follows:

  1. Start the Dynamic Web Project wizard navigating to FileNewOtherWebDynamic Web Project.


  2. Specify the project name and set the target runtime to JBoss Portal by following the points 3, 4 and 5 in the Section 2.1.1, “Creating a Web Project with JBoss Portlet Capabilities” procedure.

  3. In the Configurationarea, click the Modify button and enable JavaServer Faces,JBoss Core Portlet and JBoss JSF Portlet facets. Click the OK button.


  4. You may leave the next two wizard pages with their defaults, just press the Next button to proceed.

  5. On the JBoss Portlet Capabilities page, select Portlet Target Runtime Provider and click the Next button.


  6. Next wizard page is for configuring JSF capabilities. You can leave everything as it is here.


  7. On the JBoss JSF Portlet Capabilities page, select JSF Portlet Target Runtime Provider as the JSF portlet implementation library. It will copy Portlet Bridge libraries from the server runtime to the project classpath.


    Tip:

    On this page, it is also possible to add the RichFaces libraries from the RichFaces distribution by checkingAdd/Change Richfaces Libraries.

  8. Click the Finish button. The project will be created in the workbench.

This chapter covers the steps required to configure a Seam portlet within a Seam project with the help of the JBoss Portlet Tools features.

One of the following two procedures can be used to create a Seam project with JBoss Portlet capabilities enabled:

  1. Create a dynamic Web project with the Seam and JBoss Portlets facets enabled (see Section 2.3.1.1, “Creating a Dynamic Web Project with Seam and JBoss Portlet Capabilities”)

  2. Create a Seam project with the JBoss Seam portlet configuration using the wizard JBoss Seam Tools provides and follow all the wizard steps to enable JBoss Portlet capabilities (see Section 2.3.1.2, “Creating a Seam Project with JBoss Portlet Capabilities”)

To create a dynamic Web project with Seam and JBoss Portlet capabilities you should complete the following steps:

  1. Select. FileNewOtherWebDynamic Web Project. The New Dynamic Web Project wizard will then be displayed.


  2. Give the project a name and follow the steps 3, 4, 5 of the Section 2.1.1, “Creating a Web Project with JBoss Portlet Capabilities” procedure to set the target runtime.

  3. In the Configuration area of the first wizard page, select JBoss Seam Portlet Project v2.0. It will add needed facets to the project.

    Tip:

    If you now click the Modify button, you should see theJavaServer Faces,Jboss Portlets and Seam facets enabled.


  4. The next two pages are for adjusting the project Java and Web modules. They include the default values, so you can skip them by clicking the Next button.

  5. On the Jboss Portlet Capabilities page, select Portlet Target Runtime Provider as the portlet implementation library.

  6. The next page is for configuring JSF capabilities. As it contains the default values, just click the Next button to proceed.

  7. On the Seam Facet page, set a Seam runtime and a connection profile.

    Tip:

    For details about how to set a Seam runtime and a connection profile, see Configure Seam Facet Settings in the Chapter 2 of the Seam Dev Tools Reference Guide.


  8. On the JBoss JSF Portlet Capabilities page, select the JSF Portlet Target Runtime Provider type of the implementation library.


    It will add JBoss Portlet Bridge libraries to the project classpath.

  9. Click the Finish button to complete the project creation.

This chapter includes detailed reference information about JBoss Portlet Tools.

This section describes the JBoss Portlet Tools wizards:

The Java Portlet wizard helps you create a new Java portlet (1.0 or 2.0). It is based on the WTP's Create Servlet wizard, but adapted to JBoss Portlet. You can call it from the File or context menu of your project by following to New > Other > JBoss Tools Web > Portlet > Java Portlet.

The wizard consists of the four pages:

  1. The first one includes the next options to adjust:


  2. The second wizard page is for specifying modifiers, interfaces to implement and method stubs to generate.


    The descriptions of the options listed on this page are in the following table.


  3. The third page is for adjusting the portlet deployment descriptor settings.



  4. The last wizard page helps configure the JBoss Portlet specific descriptors.



The JSF/Seam Portlet wizard, that is merged into one JSF and Seam Portlet wizards, helps you create a JSF/Seam portlet that uses the JBoss Portlet Bridge libraries. The default values in this wizard depend on the configuration set for the project. For instance, if you set the JSF configuration, the default values in this wizard will be as for a JSF portlet.

The JSF/Seam Portlet wizard could be started from the File or context menu of your project by following to New > Other > JBoss Tools Web > Portlet > JSF/Seam Portlet.

The wizard includes three pages to adjust JSF/Seam portlet setting:

  1. The first wizard page asks to select a project to add JSF/Seam portlet and set a class file destination.



  2. The second page allows to configure a portlet deployment descriptors.



  3. The last wizard page helps you configure the JBoss Portlet specific information.


    Table 3.8. JSF/Seam Portlet Wizard. Third Page Options.

    OptionDescriptionDefault (JSF / Seam)
    Create Portlet InstanceClear the Create Portlet Instance check box, if you don't wont the wizard to create the deployment elements in the default-object.xml and portlet-instances.xml filesSelected
    If ExistsSelect one of two options:
    • overwrite - destroys the existing object and creates a new one based on the content of the deployment

    • keep - maintains the existing object deployment or creates a new one if it does not exist

    overwrite
    Instance NameEnter a name of the portlet instance that the portlet window representsJSFPortletInstance / SeamPortletInstance
    Page NameIf set, the portlet page is created with the name definedJSFPortlet / SeamPortlet
    Window NameEnter a name of the portlet windowJSFPortletWindow / SeamPortletWindow
    Parent Reference

    Define a reference to the parent object.

    For example, default means that the page appears in the default portal.

    default
    RegionSpecify the region where the window should appear on the pagecenter
    HeightDefine the height of the window1
    Initial Window StateSet the window state indicator by selecting one of three states defined by the JSR-168 specification:
    • normal - a portlet shares this page with other portlets

    • minimized - a portlet may show very little information or none at all

    • maximized - a portlet may be the only portlet displayed on this page

    maximized
    Create JBoss Application

    Select to add the jboss-app.xml descriptor.

    riPortletApp / seamPortletApp - the default name of the JBoss application. You can change it by typing a new one in the JBoss Application Name field.

    Selected
    Add the jboss-portlet.xml fileSelect to create the jboss-portlet.xml fileSelected
    Copy JSF TemplatesSelect to add the folder with JSF templates (edit.jsp, help.jsp, view.jsp) to the projectCleared

In conclusion, with this document you could easily get started with JBoss Portlet Tools. The above chapters walked you through the steps on how to organize a web project with JBoss Portlet capabilities enabled, create a Java portlet, JSF or Seam portlet and deploy them to JBoss Portal. The document also includes the reference of JBoss Portlet Tools features.

If you have questions or suggestions concerned both the documentation and tools behavior, you are welcome to JBoss Tools Users forum.

Please, use Jira to report bugs and requests on documentation.