Portal Guide

CHAPTER 23

Developing Portlets

This chapter describes methods for developing and running custom portlets in exteNd Director. It includes the following topics:

 
Top of page

Creating a portlet class

This section describes several ways to create a portlet class to run with the exteNd Director portal. If you use exteNd Director portlet development tools, such as pageflow design tools or the portlet wizards, the following operations are performed for you automatically:

 
Top of section

Using pageflow design tools

exteNd Director provides design tools for developing a specialized type of portlet called a pageflow, without the need for Java coding.

For an in-depth discussion about pageflows and how to use these design tools, see the Pageflow and Form Guide.

 
Top of section

Using the Portlet Wizard

The Portlet Wizard allows you to create Java Portlet 1.0-compliant portlets that can take advantage of exteNd Director extensions to Java Portlet 1.0.

Creating a portlet with the Portlet Wizard

Procedure To create a custom portlet using the Portlet Wizard:

  1. In exteNd Director, select File>New>File.

    The New File dialog opens.

  2. Select the Portlet tab, choose Portlet, then click OK.

    The first panel of the Create a New Portal Portlet Wizard opens.

  3. Enter the following information:

    Field

    What to specify

    Class name

    Enter the name you want to use for the portlet class.

    Package

    Enter a package name for the portlet.

    If the package does not exist, the wizard creates it in the root of the resource JAR in the target resource set. If you do not specify a package, the wizard puts the portlet class in the root of the resource JAR within the target resource set.

    Resource Set

    Select the resource set where the portlet fragment deployment descriptor should be stored. Resource sets provide dynamic deployment of design-time changes.

    For more information    For more information about resource sets, see the chapter on using the resource set in an exteNd Director application.

    Include logging code

    Check or uncheck this box to indicate whether you want logging code added to your portlet. When you check this box, the wizard automatically adds code that lets you send messages to the log when the logging level is set to the trace level.

    Content types

    Check the content types supported by the portlet. Portlets can support multiple content types.

    Data definition (for portlets using the transcoding engine)

    Specify a data definition file for the portlet. The data definition file for a portlet determines how the portlet will transcode data for wireless support.

  4. Click Next.

    The second panel of the wizard opens.

  5. Enter the following information:

    Field

    What to specify

    Description

    Enter a text description of the portlet.

    Display Name

    Enter a name for the portlet.

    NOTE:   The display name is not used by the exteNd Director portal.

    Title

    Enter a title for your portlet.

    The title is used for displaying the portlet in lists and on decorators.

    Short Title

    Enter a short title for the portlet.

    NOTE:   The short title is not used by the exteNd Director portal.

    Expiration Cache

    Enter the time in seconds after which the portlet's cached content expires.

    To disable caching for the portlet, enter 0.

    To specify that the portlet's cached content never expire, enter -1.

    Modes

    Check the modes that the portlet supports.

    NOTE:   The new portlet automatically supports View mode, in compliance with Java Portlet 1.0.

    For more information    For more information, see the section on portlet modes.

  6. Click Finish.

    A pop-up window opens, indicating when the Portlet Wizard has finished creating the portlet.

  7. Click OK to dismiss the pop-up window.

    The Wizard builds the portlet class and displays Java source code that meets the minimum requirements for a Java Portlet 1.0-compliant portlet. The wizard also creates the necessary files to support dynamic loading, as described in What the Portlet Wizard generates.

  8. Add your custom code to the portlet.

  9. Compile the portlet.

  10. Test your changes, as described in Testing a portlet.

What the Portlet Wizard generates

The Portlet Wizard performs the following actions for each portlet you create:

  1. Builds the portlet class file and stores it in the resource set you specified, based on what you entered for Package Name.

  2. Creates a portlet fragment deployment descriptor in the portal-portlet directory of the target resource set. This is an XML file that describes the portlet, based on the preferences you specified in the Portlet Wizard.

    The name of the descriptor file matches the name of the portlet class. Following is an example of a simple portlet fragment deployment descriptor whose name is CreateNewUser.xml:

      <portlet xmlns="http://www.novell.com/xml/ns/portlet-fragment" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
          <description>Creates new user</description>
          <portlet-name>CreateNewUser</portlet-name>
          <display-name>Create New User</display-name>
          <portlet-class>com.novell.portlets.CreateNewUser</portlet-class>
          <expiration-cache>30</expiration-cache>
          <supports>
              <mime-type>text/html</mime-type>
              <portlet-mode>edit</portlet-mode>
          </supports>
          <portlet-info>
              <title>Create New User</title>
              <short-title>Create User</short-title>
          </portlet-info>
          <supported-option>edit</supported-option>
          <auto-register enabled="true"/>
      </portlet>
    

    NOTE:   With the portlet class and portlet fragment deployment descriptor stored in the resource set, exteNd Director dynamically loads any changes you make to the portlet during development. As a result, the changes are immediately reflected in the runtime environment on the server, allowing you to test them without having to redeploy the entire application.

    For more information    For more information, see the sections on support for dynamic loading of portlets and on portlet fragment deployment descriptors.

  3. Sets the portlet to be registered automatically at deployment in the portlet fragment deployment descriptor, as follows:

      <auto-register enabled="true"/>
    

    If you don't want the portlet to be registered automatically, change the setting to:

      <auto-register enabled="false"/>
    

 
Top of section

Generating a portlet using a Web Service

You can create a portlet that consumes an existing Web Service by invoking the Portlet using a Web Service Wizard. It combines the abilities of the Web Service Wizard and the Portlet Wizard to:

For more information    The Web Service Wizard is described in the Web Service Wizard chapter and the chapter on generating Web Service consumers in Utility Tools.

For more information    The Portlet Wizard is described above in Using the Portlet Wizard.

Starting the wizard

Procedure To start the Portlet using a Web Service Wizard:

  1. Open an exteNd Director project in which you want the portlet created.

    The portlet files will be generated in this project's resource set.

  2. Select File>New>File.

    The New File dialog opens.

  3. Select the Portlet tab, choose Portlet using a Web Service, then click OK.

    The first panel of the wizard opens.

  4. Complete each panel of the wizard, as described in the Web Service Wizard chapter in Utility Tools.

What it does

The wizard uses the WSDL file, data type mappings, and service address URL you provide on its panels to generate the following Java classes and descriptor information. The generated classes are stored in your project's resource set on a path that matches their package name (which is generated from the target namespace defined in the WSDL).

What the wizard generates

Details

Portlet class

xxx_PORTLET.java

(where the xxx portion of the name is derived from the WSDL)

Web Service classes

The standard files for Web Service access:

  • xxx.java remote interface

  • xxxService.java service interface

  • xxxServiceImpl.java service implementation class

  • xxx_Stub.java stub class

Type classes

Application-specific files (JavaBeans, marshallers, holders) for mapping the complex types defined in the WSDL (via XML Schema) to Java

Portlet fragment deployment descriptor

xxx_PORTLET.xml in the resource set's portal-portlet directory

Using the generated portlet

You can edit the generated portlet class and descriptor file as needed to fully implement your portlet. At minimum, you must finish coding the Web Service method calls in the executeRemote() method of the portlet class. The wizard generates these calls as comments, for example:

  private Object executeRemote() throws javax.portlet.PortletException {
      try {
          AutoloanSoap remote = getRemote();
  
          .
          .
          .
  
          //return remote.calculate(double, double, double);
          return null;

Uncomment each method call you want to execute and provide appropriate arguments:

  return remote.calculate(24, 8, 15000);
  // return null;

When you finish making your changes, the portlet should be ready to compile and use.

 
Top of section

Importing Java Portlet 1.0-compliant portlets from other sources

If you do not want to use exteNd Director portlet development tools, you can import portlets from other sources into the resource set of an exteNd Director portal application WAR—as long as the following conditions are met:

Procedure To import portlets into an exteNd Director portal application WAR:

  1. Package the portlets as described above.

  2. Follow the procedure described in the section on importing resources into a view.

 
Top of page

Creating a portlet definition

exteNd Director pageflow design tools and the portlet wizards automatically create and register one portlet definition that inherits all properties from the portlet class you create. However, in some instances, portal administrators may want to create additional definitions—for example, if a definition is needed that inherits all the characteristics of the portlet class, but uses different initialization parameters.

You create a new portlet definition by creating a new portlet descriptor—either as a new portlet fragment deployment descriptor or new <portlet> sections in portlet.xml and novell-portlet.xml. This section describes both approaches.

Procedure To create a new portlet definition as a portlet fragment deployment descriptor:

  1. Create a new portlet fragment deployment descriptor by copying the one that was created for your portlet class.

  2. Change <portlet-name> to a new, unique name.

  3. Change other properties and add new properties as desired.

  4. Keep the reference to the original portlet class in <portlet-class>.

  5. Save the descriptor file in the <portal-portlet> section of your application's resource set with the same name as <portlet-name>.

  6. Register the new portlet definition as described in Registering a portlet definition.

For more information    For more information, see the section on portlet fragment deployment descriptors.

Procedure To create a new portlet definition by modifying portlet.xml:

  1. With your application open in the Director Designer, open portlex.xml.

  2. Find the <portlet> section that describes the portlet of interest.

  3. Copy and paste a new <portlet> section after the original one.

  4. In the new <portlet> section:

    1. Change <portlet-name> to a new, unique name.

    2. Change other properties and add new properties as desired.

  5. Keep the reference to the original portlet class in <portlet-class>.

  6. Save portlet.xml.

  7. If you want to specify exteNd Director value-added properties for the new definition, open novell-portlet.xml and repeat Step 2 through Step 3.

  8. Save novell-portlet.xml.

  9. Rebuild and redeploy the application.

  10. Register the new portlet definition as described in Registering a portlet definition.

 
Top of page

Registering a portlet definition

Portal administrators register portlet definitions using the Portlet Management section of the Director Administration Console (DAC). A registered portlet definition is called a portlet registration. At registration time, administrators have the opportunity to change preferences and settings for the portlet registration. See the section on registering a portlet definition.

 
Top of page

Testing a portlet

After completing the registration process, you can unit test portlet registrations by running them directly in a browser.

Procedure To run a portlet directly in a browser:

 
Top of page

Adding portlets to portal pages

After unit testing your portlet, you can add it to one or more portal pages. exteNd Director supports container, shared, and personal pages, as described in the chapter on working with portal pages.

All users can add portlets to their own personal pages, while only authorized users can add portlets to container and shared pages.

For more information    To learn how to use portlets with portal pages, see the following references:

 
Top of page

Deleting portlets from portal applications

Portal administrators can delete portlets from a portal application by following these steps:

  1. Delete the portlet from all portal pages.

    The following sections describe how to remove portlets from portal pages:

  2. Unregister the portlet.

    See Unregistering a portlet.

  3. Delete the portlet fragment deployment descriptor.

  4. Delete the Java class that defines the portlet.



Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...