Developing Portlets

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

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 Wizard, the following operations are performed for you automatically:

Portlet deployment descriptors are updated
A portlet definition is created and registered with the exteNd Director portal
Preferences are set to the default values defined in the portlet class
Your portlet is dynamically loaded to the server, so you can test the logic without needing to redeploy your entire application

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.

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:

In exteNd Director, select File>New>File.

The New File dialog opens.
Select the Portlet tab, choose Portlet, then click OK.

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

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

Click Next.

The second panel of the wizard opens.

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, see the section on portlet modes.

Click Finish.

A pop-up window opens, indicating when the Portlet Wizard has finished creating the portlet.
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.
Add your custom code to the portlet.
Compile the portlet.
Test your changes, as described in

exteNd Director performs the following actions:
1. Builds the portlet class
2. Displays the Java source file for the portlet

What the Portlet Wizard generates

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

Builds the portlet class file and stores it in the resource set you specified, based on what you entered for Package Name.
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, see the sections on support for dynamic loading of portlets and on portlet fragment deployment descriptors.
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"/>
```

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:

Portlets must be Java Portlet 1.0-compliant
Portlets must be packaged in a JAR that contains:
- Portlet class files
- An empty portlet.xml deployment descriptor file
- One portlet fragment deployment descriptor for each portlet definition
  
  For more information, see the section on portlet fragment deployment descriptors.

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

Package the portlets as described above.
Follow the procedure described in the section on importing resources into a view.

Creating a portlet definition

exteNd Director pageflow design tools and the Portlet Wizard 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:

Create a new portlet fragment deployment descriptor by copying the one that was created for your portlet class.
Change <portlet-name> to a new, unique name.
Change other properties and add new properties as desired.
Keep the reference to the original portlet class in <portlet-class>.
Save the descriptor file in the <portal-portlet> section of your application's resource set with the same name as <portlet-name>.
Register the new portlet definition as described in Registering a portlet definition.

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

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

With your application open in the Director Designer, open portlex.xml.
Find the <portlet> section that describes the portlet of interest.
Copy and paste a new <portlet> section after the original one.
In the new <portlet> section:
1. Change <portlet-name> to a new, unique name.
2. Change other properties and add new properties as desired.
Keep the reference to the original portlet class in <portlet-class>.
Save portlet.xml.
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.
Save novell-portlet.xml.
Rebuild and redeploy the application.
Register the new portlet definition as described in Registering a portlet definition.

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.

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:

Enter the portlet path URL, using this syntax:
```
  http://host/context/portal/portlet/name of portlet registration
```
Example:

http://localhost/ExpressPortal/portal/portlet/WelcomeMessagePortlet

For more information about the portlet path URL, and other request URLs recognized by the exteNd Director portal, see the section on application requests.

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: