Extending the Administration Console

Creating Portlets That Match the Administration Console

This section describes how to add a portlet that uses the Administration Console's JSP templates, styles, and user input controls. For example, you can add portlets that render your content as one of the following:

A table in the ContentBook that summarizes the resources you have provided and that enables users to navigate to a specific resource or to invoke actions on the resource from the table. (See Figure 2-4 for an example of a WebLogic Server table.)
A tab in the ContentBook that enables users to monitor or configure resources that you have provided.

Figure 5-1 illustrates the process. The steps in the process, and the results of each are described in Table 5-1. Subsequent sections detail each step in the process.

Figure 5-1 Administration Console Extension Development Overview

Administration Console Extension Development Overview

Table 5-1 Model MBean Development Tasks and Results

Step	Description	Result
1. Create and Use a Message Bundle.	Create a text file that contains a name/value pair for each text string that you want to display in your extension.	One or more`.properties` files.
2. Create Struts ActionForms and Actions.	To render HTML forms and tables that function as forms, the Administration Console uses JSP tags that load data from Java beans. To submit user input, the JSP tags forward to Struts Actions. Some JSP tags require the use of Struts ActionForms to populate the Java beans and make them available to the JSP. If you use Administration Console JSP tags, you must create your own Struts ActionForms and Actions.	A Struts configuration file, Java beans, and Java classes that implement `org.apache.struts.action.ActionForm` and `org.apache.struts.action.Action`.
3. Create JSPs that Use BEA Templates and JSP Tags.	WebLogic Server provides JSP templates that you can import into your JSPs. It also provides a JSP tag library to render the same UI controls that the Administration Console uses.	JSPs that match the Administration Console styles and structure.
4. Create a .portlet XML File.	Create a portlet that causes Struts to instantiate your ActionForm. The ActionForm populates Java beans and forwards to a JSP.	A `.portlet` XML file that defines a portlet and configures it to launch a Struts action.
5.Create Other Portal Framework Files and Deploy the Extension.	Create XML files that define a location for your extension. Then archive your extension files as a JAR file and copy it to your domain's `console-ext` directory.	A `.pinc` XML file that defines a page or book control (optional), a `netuix-extension.xml` file that describes where to locate your extension, and a JAR file that automatically deploys.

Create and Use a Message Bundle

BEA recommends that you define all of the text strings that your JSP displays in a message bundle.

To create and use a message bundle:

Create a text file that contains name/value pairs (properties) for each string you want to display. Use the equal sign (=) as the delimiter between the name and value, and place each property on its own line.

For example: myextension.myTab.introduction=This page provides monitoring data for my application. myextension.myTab.TotalServletHits.label=Total hits for my servlet.

Save the file as dev-dir/WEB-INF/classes/bundle.properties where

dev-dir is the root directory of your extension
bundle is a unique value (do not use global, which is the name of a WebLogic Server bundle). Consider using your company name as the value for bundle.

Save each localized version of the properties file as dev-dir/WEB-INF/classes/bundle_locale.properties

where locale is a locale code supported by java.util.Locale. See Locale in the J2SE API Specification.
For example, mycompany_ja.properties.
Make sure to provide one file named bundle.properties; this is the default file that is used if a user has not specified a locale.

To use the bundle in your JSPs:

Import the JSTL fmt.tld tag library:
<%@ taglib uri="/WEB-INF/fmt.tld" prefix="fmt" %>

Declare the name of your bundle:
<fmt:setBundle basename="bundle" var="current_bundle" scope="page"/>
where bundle is the name you used in the previous step.

When you want the JSP to output a string, use the following JSP tag:
<fmt:message key="property-name" bundle="${current_bundle}"/>

For example: <fmt:message key="myextension.myTab.introduction" bundle="${current_bundle}"/>

Create Struts ActionForms and Actions

All WebLogic Server JSP tags that display and submit forms (and tables that function as forms) assume that Apache Struts is the controller agent. The JSP tags use Java beans that are populated by Struts ActionForms (form beans) and submit user input to a Struts Action. For information on Apache Struts, see The Apache Struts Web Application Framework at http://struts.apache.org/.

Some tags, such as <wl-extension:table>, require the form bean to contain a property that is a collection of Java beans. Each bean in the collection describes a single object or component that is rendered as a row in the table. For information on each Administration Console JSP tag and the Java bean properties that it requires, see WebLogic Server JSP Tags Reference.

If your extension manages WebLogic Server resources, create Struts ActionForms that populate Java bean properties with attribute values from WebLogic Server Managed Beans (MBeans). Similarly, create Struts Actions that set MBean values or invoke MBean operations. For information on working with WebLogic Server MBeans, see Developing Custom Management Utilities with JMX and Developing Manageable Applications with JMX.

Create a Named Struts Module

A Struts module is a Struts configuration file, message bundle, and other related resources. All Struts applications must have one default module. As of Struts 1.1, applications can have multiple modules, each of which must be uniquely named. For more information, see the Struts Newbie FAQ at http://struts.apache.org/faqs/newbie.html#modules.

Because the WebLogic Server Administration Console already uses the default module, you must create your own module for your extension. If you follow WebLogic Server naming conventions, the Administration Console will automatically discover your module and register it with the Apache Struts controller servlet.

To create a named Struts module for your Administration Console extension:

Save your Struts configuration file as follows:
dev-dir/WEB-INF/struts-auto-config-MyModule.xml
where:

dev-dir is the root of your Administration Console
MyModule is a name that you have chosen for your module. Consider using the name of your company to avoid possible naming conflicts

When you define portlets that forward to your Struts actions, include the module="/MyModule" attribute in the portlet's <netuix:portlet> element (see Example: The Form in the Domains: Configuration: General Portlet).

For information on using additional features of Struts modules, see Configuring Applications in the Apache Struts User Guide.

Example: The Form in the Domains: Configuration: General Portlet

The Domains: Configuration: General portlet renders a form that provides configuration data for the domain. When the Administration Console loads this portlet:

The portlet forwards to the Struts DomainConfigGeneral action path, which refers to an ActionForm that is defined in a Struts configuration file. The configuration file and associated resources are in a Struts module named core.

Below is an excerpt from the portlet's .portlet file:
<netuix:portlet definitionLabel="CoreDomainDomainConfigGeneralPortlet" title="core.domain.domainconfiggeneral.portlet.title"> <netuix:strutsContent module="/core" action="DomainConfigGeneral" refreshAction="DomainConfigGeneral"/> </netuix:portlet>

When the Struts controller servlet receives the request from the portlet, it:

Instantiates the form bean that is named by the <action path="DomainConfigGeneral"> element in the Struts configuration file. (See Listing 5-1.)

This form bean, domainConfigGeneralForm, contains three properties:
name, which identifies the bean
handle, which is the name of an Action class. The <wl-extension:form> JSP tag invokes this Action when a user submits the form.
domainConfigGeneral, which is a Java bean whose properties correspond to attributes in the WebLogic Server DomainMBean.

Launches the ActionForm class that is specified by the <action path="DomainConfigGeneral"> element in the Struts configuration file.

This class, com.bea.console.actions.core.domain.DomainConfigGeneralAction, connects to an MBean server, gets the value of the DomainMBean attributes, and populates the domainConfigGeneral Java bean with the MBean attribute values.

After the ActionForm instantiates and populates a form bean, it loads the DomainConfigGeneralForm.jsp and makes the form bean available to the JSP.

Listing 5-1 ActionForm for the Domains: Configuration: General Portlet

...

<form-bean name="domainConfigGeneralForm"
   type="org.apache.struts.validator.DynaValidatorForm">
   <form-property name="name"
      type="java.lang.String"/>
   <form-property name="handle"
      type="com.bea.console.handles.Handle"/>
   <form-property name="domainConfigGeneral"
      type="com.bea.console.cvo.core.domain.DomainConfigGeneralBean"/>
</form-bean>

...

<action path="/DomainConfigGeneral"
   type="com.bea.console.actions.core.domain.DomainConfigGeneralAction"
   name="domainConfigGeneralForm"
   parameter="tab"
   scope="request"
   validate="false">
   <forward name="success"
      contextRelative="true"
      path="/jsp/core/domain/DomainConfigGeneralForm.jsp"/>
</action>

Create JSPs that Use BEA Templates and JSP Tags

Most portlets in the Administration Console JSPs that are based on the tableBaseLayout_netui and configBaseLayout_netui templates. For information about these templates, see WebLogic Server JSP Templates.

The following sections describe how to create JSPs that use these templates:

Set Up Your Development Environment

The Administration Console JSP templates require the use of JSP tags from the JSP Standard Tag Library (JSTL), the BEA Administration Console Extension Tag Library, and the Apache Beehive Page Flows Tag Library.

The WebLogic Server runtime environment already provides these tag libraries. For development support, add the following tag libraries to your development environment:
WL_HOME/server/lib/consoleapp/webapp/WEB-INF/beehive-netui-tags-html.jarWL_HOME/server/lib/consoleapp/webapp/WEB-INF/fmt.tldWL_HOME/server/lib/consoleapp/webapp/WEB-INF/console-html.tld

Create a Table JSP

A table JSP uses a table to summarize a set of resources and provides navigation to those resources (see Figure 2-4). If your extension manages multiple resources or multiple instances of a single resource, create a table JSP.

Note: Tables can contain buttons and checkboxes, which enable you to select one or more rows and invoke an action for the selected items. For information about this feature, see <wl-extension:table> in WebLogic Server JSP Tags Reference.

Before you create a table JSP, create a Struts ActionForm that populates a form bean and forwards to your JSP. (See Create Struts ActionForms and Actions.) The form bean must contain the following minimal properties:

A property named name, which identifies the form bean
A property that contains an Array of Java beans. Each of these Java beans (row beans) must contain one property for each table row that you want to render.

For example, to render the Servers table in the Administration Console, each server instance in the domain is represented by its own row bean. The row bean's properties define each server's name, listen port, listen address and other information.

To create a table JSP (see Listing 5-2):

Create a JSP and save it in your development directory. Consider creating a subdirectory to contain all of the JSPs in your extension. For example, dev-dir/jsp
where dev-dir is your development directory. For more information, see Archive and Deploy the Extension.

Import JSP tag libraries by including the following tags:

<%@ taglib uri="/WEB-INF/console-html.tld" prefix="wl-extension" %>
<%@ taglib uri="/WEB-INF/fmt.tld" prefix="fmt" %>
<%@ taglib uri="/WEB-INF/beehive-netui-tags-template.tld" prefix="beehive-template" %>

For information about these tag libraries, see JSP Tag Libraries.

(Optional) If you plan to use <fmt:message> tags to display localized text, use <fmt:setBundle/> to specify the name of the message bundle.

This <fmt:setBundle/> tag enables you to specify the bundle name once, and then refer to this value from <fmt:message> tags by variable.

Declare the JSP template for tables by creating the following opening tag:

<beehive-template:template templatePage="/layouts/tableBaseLayout_netui.jsp">
Do not close the tag yet. All other JSP tags in a table JSP are nested in this template tag.

Create a <beehive-template:section name="configAreaIntroduction"> tag. Inside this tag, provide an introductory sentence or paragraph that describes the table. This description is rendered above the table.

Create the following opening tag:
<beehive-template:section name="table">

Do not close the tag yet.

Create an opening <wl-extensions:table> tag and specify values for the following minimal attributes:

name, specify the name of the form bean that you configured for this table.
property, specify the name of the form-bean property that contains row beans.
bundle, (optional) specify the name of a message bundle that contains localized names of your column headings.
captionEnabled, (optional) specify "true" to generate a title above the table.

If you specified "true" for the captionEnabled attribute, create a <wl-extension:caption> tag. Inside this tag, provide a caption for the table.

For each property in the row bean that you want to display in the table, create a <wl-extension:column> tag and specify values for the following attributes:

property, specify the name of the row bean property
label, specify a key in your message bundle to display as the column heading

If you want the text in a column to be a hyperlink, nest a <wl-extension:column-link> tag in the <wl-extension:column> tag. For the <wl-extension:column-link> tag's portlet attribute, specify the definitionLabel of the portlet to which you want to link.

Instead of using <wl-extension:column-link> and the definitionLabel of a portlet, you can use <wl-extension:column-dispatch>, the value of metadata that you have defined for a portlet, and the value of an additional property that you must include in this table's form bean. Using metadata specify a linking target enables you to forward to all portlets that contain the specified metadata. See column-dispatch in the WebLogic Server JSP Tag Reference.

Close the <wl-extension:table>, <beehive-template:section>, and <beehive-template:template> tags.

Listing 5-2 Example: Simple Table JSP

<%@ page language="java" %>
<%@ taglib uri="/WEB-INF/console-html.tld" prefix="wl" %>
<%@ taglib uri="/WEB-INF/fmt.tld" prefix="fmt" %>
<%@ taglib uri="/WEB-INF/beehive-netui-tags-template.tld" prefix="beehive-template" %>

<fmt:setBundle basename="core" var="current_bundle" scope="page"/>

<beehive-template:template templatePage="/layouts/tableBaseLayout_netui.jsp">

   <beehive-template:section name="configAreaIntroduction">
      <fmt:message key="core.server.servertable.introduction"
            bundle="${current_bundle}"/>
   </beehive-template:section>

   <beehive-template:section name="table">
      <wl-extension:table name="extensionForm"
             property="contents"
             captionEnabled="true"
            bundle="core">

         <wl-extension:caption>
            <fmt:message key="server.table.caption" 
                 bundle="${current_bundle}"/>
         </wl-extension:caption>
         <wl-extension:column property="name" label="server.table.label.name">
            <wl-extension:column-link portlet="MyPortletID"/>
         </wl-extension:column>
         <wl-extension:column property="clusterName"
            label="server.table.label.cluster"/>
         <wl-extension:column property="machineName"
            label="server.table.label.machine"/>
      </wl-extension:table>

   </beehive-template:section>

</beehive-template:template>

Create a Configuration JSP

A configuration JSP uses a form to display the configuration of a resource and to enable users to modify the configuration (see Figure 2-3). You can create a read-only configuration JSP that enables users to monitor a resource.

The Administration Console JSP tags can render standard HTML input controls, such as text, text-areas, and radio buttons.

Before you create a configuration JSP, create a Struts ActionForm that populates a form bean and forwards to your JSP. (See Create Struts ActionForms and Actions.) The form bean must contain the following minimal properties:

A property named name, which identifies the form bean
A property that contains a Java bean. The Java bean must contain one property for each HTML input control that you want to render.

To create a configuration JSP (see Listing 5-3):

Import JSP tag libraries by including the following tags:

<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %>
<%@ taglib uri="/WEB-INF/console-html.tld" prefix="wl-extension" %>
<%@ taglib uri="/WEB-INF/fmt.tld" prefix="fmt" %>
<%@ taglib uri="/WEB-INF/beehive-netui-tags-template.tld" prefix="beehive-template" %>

For information about these tag libraries, see JSP Tag Libraries.

(Optional) If you plan to use <fmt:message> tags to display localized text, use <fmt:setBundle/> to specify the name of the message bundle.

This <fmt:setBundle/> tag enables you to specify the bundle name once, and then refer to this value from <fmt:message> tags by variable.

Declare the JSP template for configuration pages by creating the following opening tag:

<beehive-template:template templatePage="/layouts/configBaseLayout_netui.jsp">
Do not close the tag yet. All other JSP tags in a configuration JSP are nested in this template tag.

Create a <beehive-template:section name="configAreaIntroduction"> tag. Inside this tag, provide an introductory sentence or paragraph that describes the form. This description is rendered above the form.

Create the following opening tag:
<beehive-template:section name="form">

Do not close the tag yet.

Indicate that the next set of JSP tags output XHTML by creating the following tag:

<html:xhtml/>

Create an opening

<wl-extension:template
name="/WEB-INF/templates/form.xml">

tag.

The JSP tags that render forms can be used to render different types of forms. All form-related JSP tags output XML and the <wl-extension:template> tag specifies an XSLT template to transform the XML to XHTML. WebLogic Server provides the following templates:

/WEB-INF/templates/form.xml, which creates a form that matches Administration Console configuration pages (such as Domains: Configuration: General). This template also generates a button that submits the form.
/WEB-INF/templates/assistant.xml, which creates a form that matches Administration Console assistants.
/WEB-INF/templates/tablePreferences.xml, which creates a form that matches pages used to customize table displays in the Administration Console

Create an opening <wl-extension:form> and specify values for the following attributes:

action, specify the path of a Struts action that is invoked when a user submits this form. The Struts module that defines the action path is specified in the request.
bundle, (optional) specify the name of a message bundle that contains localized names of your column headings.
readOnly, (optional) specify "true" to make this form read-only (for example, if you are displaying read-only monitoring data).

For each property in the form bean that you want to display in the form, create a <wl-extension> tag corresponding to the type of control that you want to render (see WebLogic Server JSP Tags Reference):

<wl-extension:checkbox>
<wl-extension:chooser-tag>
<wl-extension:hidden>
<wl-extension:password>
<wl-extension:radio>
<wl-extension:select>
<wl-extension:text>
<wl-extension:text-area>

Alternatively, you can use <wl-extension:reflecting-fields>, which generates an HTML input tag for each property in a form bean. For example, for a bean property that contains a java.lang.String, the tag generates a text control; for a boolean, it generates a checkbox. This tag uses the default form bean, which is passed to the JSP in the request.

To generate text on the page that describes to users the purpose of each control, include the inlineHelpId attribute in each <wl-extension> tag in the previous step.

Close the <wl-extension:form>, <beehive-template:section>, and <beehive-template:template> tags.

Listing 5-3 Example: Simple Configuration JSP

<%@ page language="java" %>
<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %>
<%@ taglib uri="/WEB-INF/console-html.tld" prefix="wl" %>
<%@ taglib uri="/WEB-INF/fmt.tld" prefix="fmt" %>
<%@ taglib uri="/WEB-INF/beehive-netui-tags-template.tld"
   prefix="beehive-template" %>

<fmt:setBundle basename="core" var="current_bundle" scope="page"/>
<beehive-template:template templatePage="/layouts/configBaseLayout_netui.jsp">
   <beehive-template:section name="configAreaIntroduction">
      <fmt:message key="core.server.serverconfiggeneral.introduction"
           bundle="${current_bundle}"/>
   </beehive-template:section>

   <beehive-template:section name="form">
      <html:xhtml/>
      <wl-extension:template name="/WEB-INF/templates/form.xml">
         <wl-extension:form action="/CoreServerServerConfigGeneralUpdated" bundle="core">
            <wl-extension:text property="serverConfigGeneral.Name"
               labelId="core.server.serverconfiggeneral.name.label"
                inlineHelpId="core.server.serverconfiggeneral.name.
                    label.inlinehelp" />
             <wl-extension:select property="serverConfigGeneral.selectedMachine"
                 labelId="core.server.serverconfiggeneral.machine.label"
                 inlineHelpId="core.server.serverconfiggeneral.machine.
                    label.inlinehelp">
                  <wl-extension:optionsCollection
                     property="serverConfigGeneral.availableMachines"
                     label="label" value="value"/>
              </wl-extension:select>
         </wl-extension:form>
      </wl-extension:template>
   </beehive-template:section>
</beehive-template:template>

Create a .portlet XML File

A .portlet XML file defines a WebLogic Portal portlet, which is a container for content such as JSPs and Struts actions. All JSPs in the Administration Console must be contained in portlets. For more information about portlet XML files, see the Portal Support Schema Reference.

To create a portlet that contains a JSP based on WebLogic Server template and its required Struts actions:

Copy the code from Listing 5-4 and paste it into new text file.

Consider creating a subdirectory to contain all of the portlet XML files in your extension. For example, dev-dir/PortalConfig where dev-dir is your development directory. For more information, see Archive and Deploy the Extension.
Also consider adopting the following naming convention: JSP-file-name-no-extension.portlet
where JSP-file-name-no-extension is the name of the JSP file that the portlet contains. For example, if the portlet contains a JSP file named monitorEJB.jsp, then name the portlet XML file monitorEJB.portlet.

Replace the values in Listing 5-4 as follows:

Label. Provide a unique identifier that the portal framework uses to identify this portlet.
(optional) Title. Provide a default title that this portlet displays in its title bar if the Look and Feel causes the title bar to be displayed.
Struts-module. Specifies the Struts module that defines the ActionForm that you use for table and configuration JSPs. The value that you enter must be part of an XML file name that you save in /WEB-INF.

For example, if you specify "myModule" for Struts-module, the Struts controller servlet looks in the following location for action paths: /WEB-INF/struts-auto-config-myModule.xml

action-path. Specifies the path to a Struts action that is defined in your Struts module. The action must create an ActionForm and then forward to your table or configuration JSP. See Create Struts ActionForms and Actions.
refresh-action-path. Specifies the action to invoke on subsequent requests for this portlet (for example, the user agent refreshes the document).

Note that this .portlet does not specify the name of your table or configuration JSP. Instead, the name of this JSP is specified in the Struts configuration file.

Listing 5-4 Template for a Simple .portlet XML File

<?xml version="1.0" encoding="UTF-8"?>
<portal:root xmlns:html="http://www.w3.org/1999/xhtml-netuix-modified/1.0.0"
   xmlns:portal="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0"
   xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/portal/
      support/1.0.0 portal-support-1_0_0.xsd">

   <netuix:portlet definitionLabel="Label" title="Title" >
     <netuix:strutsContent module="Struts-module"
          action="action-path"
          refreshAction="refresh-action-path"/>
   </netuix:portlet>

</portal:root>

Create Other Portal Framework Files and Deploy the Extension

You can add your portlet directly to the desktop, but if you want your portlet to display as a tab or subtab in the ContentBook, you must define books or pages to contain it. In addition, you must create a netuix-extension.xml file which specifies where to locate your portlet, books, and pages and which functions as the deployment descriptor for your extension.

See Adding Portlets and Navigation Controls.