Extending the Administration Console
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
In the Administration Console, all content is contained within portlets, so even the most minimal extension must define a portlet (and content for the portlet). 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. Your extension can also add a node to the NavTreePortlet, which enables users to navigate to your portlet directly from the desktop.
This section describes how to add portlets that contain simple, static content to the Administration Console. For information on adding portlets with dynamic content, such as portlets that launch Apache Struts actions, see Creating Portlets That Match the Administration Console.
Figure 4-1 illustrates the process. The steps in the process, and the results of each are described in Table 4-1. Subsequent sections detail each step in the process.
Figure 4-1 Adding Portlets and Navigation Controls Development Overview
1. Define a Portlet. |
Create an XML file to define a portlet that the portal framework can instantiate. A portlet definition includes instructions on which type of data to load: JSPs, HTML files, Struts actions, or Beehive Page Flows. The portal's Look and Feel determines whether the portlet provides borders and minimize/maximize controls. |
|
If you want your portlet to display in a tab, subtab, or in some other location within |
||
You can create a link from the NavTreePortlet to any book or page in your extension. WebLogic Server provides default support for appending control names to the end of the existing navigation tree. If you want to insert nodes in specific locations, or if you want to create a node tree, you create your own Java classes that describe the node and node location. |
Additional entries in the Optionally, Java classes that give you more control over the node that you are adding. |
|
4. Specify a Location for Displaying Portlets or UI Controls. |
Create an XML file that describes whether you want your portal to display next to a labeled UI control or to replace the control. |
|
Organize your extension files into a standard Web application directory structure. Then archive the directory tree as a JAR file and copy it to your domain's |
To create .portlet
XML file that defines a portlet:
dev-dir
/PortalConfig
dev-dir
is your development directory.Subsequent sections will instruct you to add other files and directories to your development directory. For more information, see Archive and Deploy the Extension.
dev-dir
/portlets
or some other directory below dev-dir
.Consider using the following naming convention: content-name
.portlet
where content-name
is the name of a JSP or HTML 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
.
Label
. Provide a unique identifier that the portal framework uses to identify this portlet.Title
. Provide a default title that this portlet displays in its title bar when the Look and Feel causes the title bar to be displayed. You can override this default for each instance of this portlet (see Create a NetUI Extension XML File).URI
. Specifies the absolute path and file name of the JSP that the portlet contains starting from the root of the extension. For more information about portlet XML files, see the Portal Support Schema Reference.
Listing 4-1 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:content>
<netuix:jspContent contentUri="URI"/>
</netuix:content>
</netuix:portlet>
</portal:root>
The ContentBook
is made up of a hierarchy of books and pages. All portlets in ContentBook
display within a book or a page, and if you want to add portlets to the ContentBook
, you must create a book or page that conforms to the existing hierarchy:
Save the definitions of your books and pages in one or more portal include (.pinc
) files. Create one .pinc
file for each hierarchical grouping of controls. For example, create one .pinc
file for a book that creates a top-level tab and its subtabs. Create another .pinc
file for a page that adds a subtab to an existing WebLogic Server tab. The root element of a.pinc
file (portal:root
) can have only one direct child element; the child element can have multiple children.
The following sections describe creating books and pages:
To create a portal include (.pinc
) XML file that defines a top-level tab and one subtab:
dev-dir
.For example, dev-dir
/PortalConfig/MyApp.pinc
where dev-dir
is your development directory. For more information, see Archive and Deploy the Extension.
Book-Label
. Provide a unique identifier that the portal framework and WebLogic Server JSP tags use to forward requests to the book. This is the same type of label that WebLogic Server provides for many of its UI controls. See UI Controls in the Administration Console.Book-Title
. Provide either the text that users see as the name of the tab or a key in a message bundle that you have created. The Administration Console assumes that this value is a key, but if it cannot find the key in the specified bundle, it displays the value.Bundle
. Specify the name of a message bundle that you have created. See Create and Use a Message Bundle.Page-Label
. Provide a unique identifier that the portal framework and WebLogic Server JSP tags use to forward requests to the page. Page-Title
. Provide either the text that users see as the name of the subtab or a key in a message bundle that you have created.Metadata-Type
and Metadata-ID
. If you want to use the Administration Console's <wl:column-dispatch>
JSP tag to create a hypertext link that forwards to this page, include a <netuix:meta>
element and supply values for Metadata-Type
and Metadata-ID
. See column-dispatch in the WebLogic Server JSP Tag Reference.Portlet-Instance-Title
. This value is required by the portal support schema, but it is not used in this context. The portal framework displays the value in the portlet's title bar, but the Administration Console's Look and Feel specifies that portlets at this level of the hierarchy do not display title bars. Portlet-Instance-Label
. Provide a unique identifier that the portal framework and WebLogic Server JSP tags use to forward requests to the portlet instance. Portlet-URI
. Specify the path and file name of a portlet file that you created (see Define a Portlet). The path must be relative to the root of the portal Web application.netuix:page
elements as siblings to the netuix:page
element in Listing 4-2.For more information about portal include XML files, see the Portal Support Schema Reference.
Note the use of the following elements in the .pinc
file:
netuix:singleLevelMenu
renders one subtab for each page in the book. The book's parent UI control (which Listing 4-2 assumes is provided by WebLogic Server) is responsible for generating a top-level tab for the book.netuix:meta name="breadcrumb-context" content="handle"
adds the page's title to the history of visited pages (breadcrumbs) after a user has visited the page. The breadcrumbs display on the desktop above ContentBook
.Listing 4-2 Template for a .pinc File That Defines a Top-Level Tab with Subtabs
<?xml version="1.0" encoding="UTF-8"?>
<portal:root
xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"
xmlns:html="http://www.w3.org/1999/xhtml-netuix-modified/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:portal="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0"
xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/portal/support
/1.0.0 portal-support-1_0_0.xsd">
<netuix:book markupName="book" markupType="Book"
definitionLabel="Book-Label" title="Book-Title">
<netuix:singleLevelMenu markupType="Menu" markupName="singleLevelMenu"
skeletonUri="singlelevelmenu_children.jsp"/>
<netuix:meta name="skeleton-resource-bundle" content="Bundle"/>
<netuix:content>
<netuix:page markupName="page" markupType="Page"
definitionLabel="Page-Label" title="Page-Title"
skeletonUri="/framework/skeletons/default/wlsworkspace/
page_content.jsp">
<netuix:meta name="Metadata-Type" content="Metadata-ID"/>
<netuix:meta name="breadcrumb-context" content="handle"/>
<netuix:meta name="skeleton-resource-bundle" content="Bundle"/>
<netuix:content>
<netuix:gridLayout columns="1" markupType="Layout"
markupName="singleColumnLayout">
<netuix:placeholder flow="vertical" markupType="Placeholder"
markupName="singleColumn_columnOne">
<netuix:portletInstance markupType="Portlet"
title="Portlet-Instance-Title"
instanceLabel="Portlet-Instance-Label"
contentUri="Portlet-URI"/>
</netuix:placeholder>
</netuix:gridLayout>
</netuix:content>
</netuix:page>
<!-- Add additional netuix:page elements here -->
</netuix:content>
</netuix:book>
</portal:root>
To create a portal include (.pinc
) XML file that defines a top-level tab and no subtabs (such as Domains: Notes):
For example, dev-dir
/PortalConfig/MyApp.pinc
where dev-dir
is your development directory. For more information, see Archive and Deploy the Extension.
Page-Label
. Provide a unique identifier that the portal framework and WebLogic Server JSP tags use to forward requests to the page. Page-Title
. Provide either the text that users see as the name of the subtab or a key in a message bundle that you have created.Bundle
. Specify the name of a message bundle that you have created. See Create and Use a Message Bundle.Portlet-Instance-Title
. This value is required by the portal support schema, but it is not used in this context. The portal framework displays the value in the portlet's title bar, but the Administration Console's Look and Feel specifies that portlets at this level of the hierarchy do not display title bars. Portlet-Instance-Label
. Provide a unique identifier that the portal framework and WebLogic Server JSP tags use to forward requests to the portlet instance. Portlet-URI
. Specify the path and file name of a portlet file that you created (see Define a Portlet). The path must be relative to the root of the portal Web application.Note that Listing 4-3 defines a page, not a book, so the Administration Console Look and Feel will render the page as a tab with no subtabs.
Listing 4-3 Template .pinc File that Creates a Top-Level Tab with No Subtabs
<?xml version="1.0" encoding="UTF-8"?>
<portal:root
xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"
xmlns:html="http://www.w3.org/1999/xhtml-netuix-modified/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:portal="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0"
xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/portal/support
/1.0.0 portal-support-1_0_0.xsd">
<netuix:page markupName="page" markupType="Page"
definitionLabel="Page-Label" title="Page-Title"
skeletonUri="/framework/skeletons/default/wlsworkspace/
page_content.jsp">
<netuix:meta name="skeleton-resource-bundle" content="Bundle"/>
<netuix:content>
<netuix:gridLayout columns="1" markupType="Layout"
markupName="singleColumnLayout">
<netuix:placeholder flow="vertical" markupType="Placeholder"
markupName="singleColumn_columnOne">
<netuix:portletInstance markupType="Portlet"
title="Portlet-Instance-Title"
instanceLabel="Portlet-Instance-Label"
contentUri="Portlet-URI"/>
</netuix:placeholder>
</netuix:gridLayout>
</netuix:content>
</netuix:page>
</portal:root>
To add a subtab to an existing WebLogic Server tab, use the same code from Listing 4-3.
The location that you specify for the control determines whether the Administration Console renders it as a top-level tab or a subtab. For example, if you specify that the control is a child of the DomainConfigGeneralPage
book, then it displays as a subtab of the Domains: Configuration tab. If you specify that the control is a child of the CoreDomainConfigGeneralBook
book, then it displays as a top-level tab and a sibling of the Domains: Configuration tab.
See Specify a Location for Displaying Portlets or UI Controls.
There is no requirement for books and pages in ContentBook
to be accessible by tab or subtab. Many WebLogic Server pages that display summary tables are accessible from the NavTreePortlet but not from the tabbed interface (see Figure 2-4).
Any of the code listings in the previous sections can be located in a parent control that does not render tabs or subtabs for its children. See Specify a Location for Displaying Portlets or UI Controls.
If you created a custom security provider and used WebLogic MBeanMaker to create MBeans to manage your provider, the Administration Console automatically generates pages to display the provider's configuration data. It also generates a link to your provider pages from the Security: Providers table.
However, you can create your own pages to customize this display. If you create your own pages, you need to redirect the link in the Security: Providers table from the pages that the Administration Console generates to your custom pages.
To redirect the link, include the following element as a child of your page's <netuix:page>
element:
<netuix:meta type="configuration" content="
MBean-class-name
"/>
where MBean-class-name
is the fully qualified name of your provider's MBean class.
<netuix:page markupName="page" markupType="Page"
definitionLabel="SimpleSampleAuthorizerAuthorizerConfigCommonTabPage"
title="tab.common.label"
skeletonUri="/framework/skeletons/default/wlsworkspace
/page_content.jsp">
<netuix:meta name="configuration"
content="examples.security.providers.authorization.simple.
SimpleSampleAuthorizerMBean"/> <netuix:content>
...
You can create a link from the portlet whose user-visible title is Domain Structure (NavTreePortlet) to any book or page in your extension. The following sections describe adding nodes to the NavTreePortlet:
To append a node that links to one of your book or page controls, add the following attribute and attribute value to the <netuix:book>
or <netuix:page>
element:backingFile="com.bea.console.utils.NavTreeExtensionBacking"
<netuix:book definitionLabel="MyAppTableBook" title="MyApp.title"
markupName="book"
markupType="Book"
backingFile="com.bea.console.utils.NavTreeExtensionBacking"
>
The NavTreePortlet displays the value of the book or page element's title
attribute as the link text. If the title
attribute value is a key in your message bundle, the NavTreePortlet displays the localized value mapped to the key.
If you specify this backingFile
attribute and value for multiple controls in your extension, the NavTreePortlet appends each node entry in the order in which you have declared the controls in the NetUI Extension file.
If you want to control the location in which your node is added to the NavTreePortlet, or if you want to add a node that contains other nodes (a node tree):
This class defines one or more nodes and specifies the location for your nodes. See Create a NavTreeBacking Class.
<netuix:book>
or <netuix:page>
element in your portal include (.pinc
) file:backingFile="
your-NavTreeBacking-class
"
where your-NavTreeBacking-class
is the fully-qualified name of the class you created in step 1.
If your NavTreeBacking
Java class creates a node tree, add the backingFile
attribute to the control that is at the top of the node tree. For example, if you are adding a node tree for a book and its pages, add the backingFile
attribute to the <netuix:book>
element.
The Java class that defines your nodes must extend com.bea.console.utils.NavTreeExtensionBacking
. This class is already available in the WebLogic Server runtime environment. However, for support in your development and compiling environment, you must add the following JARs to your environment's classpath:WL_HOME
/server/lib/consoleapp/webapp/WEB-INF/lib/console.jar
WL_HOME
/server/lib/consoleapp/webapp/WEB-INF/lib/netuix_servlet.jar
where WL_HOME
is the location in which you installed WebLogic Server.
To create a NavTreeBacking
class (see Listing 4-4):
NavTreeExtensionBacking.getTreeExtension(
PageBackingContext ppCtx, String extensionUrl)
method.The portal framework passes the ppCtx
and extensionUrl
parameter values to your NavTreeBacking
class when it loads a control that contains the backingFile="
your-NavTreeBacking-class
"
attribute.
PageBackingContext
is a class in the portal framework that contains data about a portal control and methods for retrieving the data. For example, it contains the value of a control's definitionLabel
. The ppCtx
instance that is passed describes the control that invoked the getTreeExtension()
method. See com.bea.netuix.servlets.controls.page.PageBackingContext
in the WebLogic Portal 8.1.4 API Reference.
The extensionUrl
value is a URL to the control that invoked the getTreeExtension()
method.
Use the following constructor for a parent node (or for a node that contains no children):TreeNode(String
nodeId
, String
nodeName
, String
nodeUrl
)
where:
nodeId
is the value of the control's definitionLabel
. You can use PageBackingContext.getDefinitionLabel()
to get this value for the PageBackingContext
instance that was passed as a parameter to your method. Alternatively, you can enter the definitionLabel
value that is in the control's .pinc
file.
nodeName
is the text that you want to display in the NavTreePortlet.
nodeURL
is a URL to the control. Supply extensionUrl
as the value of this parameter.
TreeNode
objects as children of the top TreeNode
. For each child node, use the following constructor:TreeNode(String
nodeId
, String
nodeName
,
String nodeUrl,
TreeNode
parent
)
where:
nodeId
is the value of the control's definitionLabel
. You can not use PageBackingContext.getDefinitionLabel()
to get this value because the PageBackingContext
available to this method is for the parent node. Instead, you must enter the definitionLabel
value that is in the control's .pinc
file.
nodeName
is the text that you want to display in the NavTreePortlet.
nodeURL
is a URL to the control. Supply the following value:?_nfpb=true&_pageLabel=
definitionLabel
where definitionLabel
is the definitionLabel
of the page or book to which you want to link.
parent
is any TreeNode
that you have constructed. You can create multiple levels in your node tree by specifying a parent that is a child of node higher up in the hierarchy.
The event is broadcast to a listener in the NavTreePortlet.
Use the following constructor:NavTreeExtensionEvent(String
pageLabel
, String
url
,
String parentPath
, TreeNode
node
, int ACTION)
where:
pageLabel
is the same nodeID
value that you used when constructing the TreeNode
object for the parent node.
url
is the same nodeURL
value that you used when constructing the TreeNode
object for the parent node.
parentPath
is the name of the node under which you want your node to display. Use /
(slash) to represent the root of the navigation tree in the NavTreePortlet.
For example, if you want your node or node tree to display at the top level, specify /
. If you want your node to display as a child of Environments, specify /Environments
.
node
is the parent TreeNode that you created in step a.
ACTION
is NavTreeExtensionEvent.APPEND_ACTION
. For information about other possible actions, see NavTreeExtensionEvent
in the WebLogic Portal 8.1.4 API Reference.
Listing 4-4 Example NavTreeExtensionBacking Class
package com.mycompany.consoleext;
import com.bea.netuix.servlets.controls.page.PageBackingContext;
import com.bea.jsptools.tree.TreeNode;
import com.bea.console.utils.NavTreeExtensionBacking;
import com.bea.console.utils.NavTreeExtensionEvent;
public class CustomNavTreeExtension extends NavTreeExtensionBacking {
public NavTreeExtensionEvent getTreeExtension(PageBackingContext ppCtx,
String extensionUrl){
/*
* Construct a TreeNode for the control that has invoked this method.
*/
TreeNode node = new TreeNode(ppCtx.getDefinitionLabel(),
ppCtx.getDefinitionLabel(),extensionUrl);
/*
* Construct a child TreeNode.
*/
TreeNode node1 = new TreeNode("MyAppGeneralTabPage",
"MyApp General",
"?_nfpb=true&_pageLabel=MyAppGeneralTabPage",node);
/*
* Add the parent node (which includes its child) below the
* Environment node in the NavTreePortlet.
*/
NavTreeExtensionEvent evt =
new NavTreeExtensionEvent(ppCtx.getDefinitionLabel(),extensionUrl,
"/Environment",node, NavTreeExtensionEvent.APPEND_ACTION);
return evt;
}
}
All locations for displaying your portlets or UI controls must be specified as relative to existing controls in the Administration Console. For example, you can specify that your portlet displays on the desktop below the System Status portlet.
The following sections describe how to specify a location for your portlets or UI controls:
Most of the Administration Console UI controls are identified by a definitionLabel
, and it is this value that you use for relative positioning of your UI control. WebLogic Server provides a Look and Feel that reveals the labels in the Administration Console user interface.
Note: If you plan only to add a portlet to the desktop, you do not need to deploy the development Look and Feel.
Each labeled control displays the value of its definitionLabel
in brackets ([]) next to its user-visible title. In a separate pair of brackets, the control displays whether it is a book or a page. See Figure 4-2.
Figure 4-2 A Control Label in the Administration Console User Interface
A NetUI Extension XML file (netuix-extension.xml
) is the deployment descriptor for your extension. It declares each parent UI control in your extension and the location in which you want it to display. For more information, see the NetUI Extensions Schema Reference.
To create a NetUI Extension XML file (see Listing 4-5):
netuix-extension.xml
and save it in dev-dir
/WEB-INF
dev-dir
is your development directory. For more information, see Archive and Deploy the Extension.This element is for your information only. The portal framework does not use the data in this element.
This required element specifies the name and relative location of the Administration Console's .portal
file, which is the portal that you are extending.
<page-extension>
portlet-URI
<page-location>
<parent-label-location label="page"/>
<page-insertion-point layout-location="0"
placeholder-position="0"/>
</page-location>
<portlet-content
content-uri="" title="
title"
portlet-instance-label
orientation="top" default-minimized="false"
instance-label=""/>
</page-extension>
.portlet
file. The path must be relative to the root of the portal Web application..portlet
file.You can change the values of the layout-location
and placeholder-position
attributes to change the location of your portlet. For more information, see the NetUI Extensions Schema Reference.
<book-extension>
Admin-Console-Book-Label
<book-location>
<parent-label-location label=""/>
pinc-URI
<book-insertion-point action="append"/>
</book-location>
<book-content content-uri=""/>
</book-extension>
definitionLabel
of an Administration Console book control that renders tabs for its child books. .pinc
file that defines the book control for your tab (and optional subtabs). The path must be relative to the root of the portal Web application.definitionLabel
of an Administration Console book control that renders subtabs for its child pages. .pinc
file that defines the page control for your subtab. The path must be relative to the root of the portal Web application.Listing 4-5 Example netuix-extension.xml File
<?xml version="1.0" encoding="UTF-8"?>
<weblogic-portal-extension
xmlns="http://www.bea.com/servers/portal/weblogic-portal/8.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/servers/portal/weblogic-portal/
8.0 netuix-extension-1_0_0.xsd">
<provider-info>
<title>My Extension</title>
<version>1.0</version>
<description>Inserts a portlet on the desktop, a tab next to
Domains:Configuration, and a subtab under Domains: Configuration.
</description>
<author>Me</author>
<last-modified>02/03/2005</last-modified>
<support-url>http://www.mycompany/support/index.jsp</support-url>
</provider-info>
<portal-file>/console.portal</portal-file>
<!--Adds a portlet to the console desktop -->
<page-extension>
<page-location>
<parent-label-location label="page"/>
<page-insertion-point layout-location="0" placeholder-position="0"/>
</page-location>
<portlet-content content-uri="/portlets/desktop/desktop_view.portlet"
title="My App Status" orientation="top" default-minimized="false"
instance-label="PortletExtensionInstanceLabel"
/>
</page-extension>
<!--Adds a tab to the Domain tabs -->
<book-extension>
<book-location>
<parent-label-location label="CoreDomainConfigGeneralBook"/>
<book-insertion-point action="append"/>
</book-location>
<book-content content-uri="/page/page.pinc"/>
</book-extension>
<!-- Adds a subtab to the Domain: Configuration tab-->
<book-extension>
<book-location>
<parent-label-location label="DomainconfigTabPage"/>
<book-insertion-point action="append"/>
</book-location>
<page-content content-uri="/page/notespage.pinc"/>
</book-extension>
</weblogic-portal-extension>
To archive and deploy your extension:
For example, the netuix-extension.xml
file, which is the deployment descriptor for your extension, must be in a directory named:root-dir
/WEB-INF
If you are using a Java class to add nodes to the NavTreePortlet, the package structure must start in the following directory:root-dir
/WEB-INF/classes
If you are using a message bundle, the properties files must be in the following directory:root-dir
/WEB-INF/classes
All other resources can be in any directory structure that you choose, as long as it is below the extension's root directory (and as long as relative links from the netuix-extension.xml
file and other XML files are correct).
If the Administration Console encounters deployment errors, it outputs error and warning messages to standard out and to the Administration Server's server log file.
If you do not see error or warning messages and you do not see your extension in the Administration Console, you might have named the wrong parent UI control in your netuix-extension.xml
file. For example, if you name a parent UI control that does not render tabs for its children, then your extension is deployed but there is no menu control for accessing it.
![]() ![]() |
![]() |
![]() |