TODO: Introduction goes here

This document is organized in the following sections:

Architecture

How to Develop an Administrator Console Extension (ACE)

Different ways of structuring

The whole concept behind creating an ACE for Geronimo is that you are adding an extension in the form of portlets to the administrator console. In order to get your extenstion added, your deployable archive must do two things:

1. link to section declare a dependency on the "pluto-portal"
2. link to section define an ACEGBean.

   What should be in my deployable archive (WAR or CAR)?

   1. A geronimo-web.xml file which:
      1. declares the dependency on the pluto-portal
      2. declares the ACEGBean
   2. (Optional)
      1. Your portlets
      2. Your portlets + your related component

Create a portlet

In their most fundamental state, an ACE defines where to place new/old portlets in your console. Portlets are the fundamental building block of the administrator console. We are using Pluto 2.x as our portal engine since it closely conforms to JSR 168 [link to JSR 168]. We will not go into the details of how to develop portlets since you can find many tutorials and tools that are much better at this. [many tutorial links here]. You will need the appropriate "web.xml" and "portlet.xml" files defined. As a simple example, refer to the [link to section] HelloWorldPortlet defined at the end of this section.

Add an ACEGBean

To add an ACEGBean to your deployable archive file, you need to include the following to your "geronimo-web.xml" deployment plan:

1. dependency on the pluto-portal

   <dependencies>
       ...
   <dependency>
       <groupId>org.apache.geronimo.portals</groupId>
       <artifactId>pluto-portal</artifactId>
   </dependency>
   </dependencies>
   

2. declaration of an ACEGBean

   <gbean name="example" class="org.apache.geronimo.pluto.ACEGBean">
       <attribute name="pageTitle">Testing</attribute>
       <attribute name="portletContext">/HelloWorldPortlet</attribute>
       <attribute name="portletList">[HelloWorldPortlet]</attribute>
   </gbean>
   

   where the attributes are defined as follows:

• pageTitle: The name of the page to add these portlets to (new or existing)
• portletContext: The context of where the portlets are installed.
• portletList: A comma-delimited list of the portlets to be added to this page.

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.2">
    <environment>
        <moduleId>
            <groupId>org.apache.geronimo.portals</groupId>
            <artifactId>pluto-example</artifactId>
            <version>1.0-SNAPSHOT</version>
            <type>war</type>
        </moduleId>
        
        <dependencies>
            <dependency>
                <groupId>org.apache.geronimo.portals</groupId>
                <artifactId>pluto-container</artifactId>
            </dependency>
        </dependencies>
    </environment>
    
    <context-root>/HelloWorldPortlet</context-root>

    <gbean name="PlutoTest" class="org.apache.geronimo.pluto.ACEGBean">
        <attribute name="pageTitle">Hello</attribute>
        <attribute name="portletContext">/HelloWorldPortlet</attribute>
        <attribute name="portletList">[HelloWorldPortlet]</attribute>
    </gbean>
</web-app>

Putting it together

Add your modified "geronimo-web.xml" deployment plan to your WAR or CAR in the WEB-INF folder. Also, if you are including portlets, your archive file should contain the appropriate class files as well as the "web.xml" and "portlet.xml" files.

Deploying the application

Deploy the archive as you normally would either using the "deploy" command or by using the Administrator Console's "Deploy New" or "Plugins".

1. Command Line: <geronimo bin folder>/deploy.bat deploy <path to war>
   Example:
   cd c:/g/target/geronimo-tomcat6-minimal-2.0-SNAPSHOT/bin/
deploy.bat deploy c:/HelloWorldPortlet.war
2. Using the Admin Console:

Verifying installation

Go to http://localhost:8080/pluto/ to verify that the portlets were added to the correct page. (You may need to refresh the browser if you deployed from the command line.)

Sample Extension

package org.apache.pluto.examples;

import java.io.IOException; 
import java.io.PrintWriter;

import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

/**
 * A very simple portlet example.
 * This portlet displays 'Hello World' to the end user
 */
public class HelloWorldPortlet extends GenericPortlet {

    // This function is called when a user requests to view this portlet (by
    // navigating to the webpage in Pluto)
    public void doView(RenderRequest request, RenderResponse response)
            throws PortletException, IOException {

        // Set the response to read HTML
        response.setContentType("text/html;charset=UTF-8");

        // Required call for use of getWriter() and getPortletOutputStream()
        PrintWriter out = response.getWriter();
        // Write content to the portlet
        out.println("<h1>Hello World</h1>");
    }
}

Download the example WAR