Adding Functionality to the Administration Console

The integration-point elements in the console-config.xml file specify attributes for the user interface features that you choose to implement. The example file provides examples of most of the available kinds of integration points at this release. Your own add-on component can use some or all of them.

For each integration-point element, specify the following attributes.

id

An identifier for the integration point.

parentId

The ID of the integration point's parent.

type

The type of the integration point.

priority

A numeric value that specifies the relative ordering of integration points for add-on components that specify the same parentId. A lower number specifies a higher priority (for example, 100 represents a higher priority than 400). The integration points for add-on components are always placed after those in the basic Administration Console. You might need to experiment to place the integration point where you want it. This attribute is optional.

content

The content for the integration point, typically a JavaServer Faces page. In the example, you can find the JavaServer Faces pages in the directory project/src/main/resources/.

The following topics are addressed here:

• Adding a Node to the Navigation Tree

• Adding Tabs to a Page

• Adding a Task to the Common Tasks Page

• Adding a Task Group to the Common Tasks Page

• Adding Content to a Page

• Adding a Page to the Administration Console

Adding a Node to the Navigation Tree

You can add a node to the navigation tree, either at the top level or under another node. To add a node, use an integration point of type org.glassfish.admingui:navNode. Use the parentId attribute to specify where the new node should be placed. Any tree node, including those added by other add-on components, can be specified. Examples include the following:

tree

At the top level

applicationServer

Under the GlassFish Server node

applications

Under the Applications node

resources

Under the Resources node

configuration

Under the Configuration node

webContainer

Under the Web Container node

httpService

Under the HTTP Service node

If you do not specify a parentId, the new content is added to the root of the integration point, in this case the top level node, tree.

Example 3-2 Example Tree Node Integration Point

For example, the following integration-point element uses a parentId of tree to place the new node at the top level.

        <integration-point 
                id="sampleNode" 
                parentId="tree" 
                type="org.glassfish.admingui:treeNode" 
                priority="200" 
                content="sampleNode.jsf" 
        />

This example specifies the following values in addition to the parentId:

• The id value, sampleNode, specifies the integration point ID.

• The type value, org.glassfish.admingui:treeNode, specifies the integration point type as a tree node.

• The priority value, 200, specifies the order of the node on the tree.

• The content value, sampleNode.jsf, specifies the JavaServer Faces page that displays the node.

The example console-config.xml file provides other examples of tree nodes under the Resources and Configuration nodes.

Creating a JavaServer Faces Page for Your Node

A JavaServer Faces page for a tree node uses the tag sun:treeNode. This tag provides all the capabilities of the Project Woodstock tag webuijsf:treeNode.

Example 3-3 Example JavaServer Faces Page for a Tree Node

In the example, the sampleNode.jsf file has the following content:

<sun:treeNode 
        id="treeNode1"
        text="SampleTop"
        url="/sample/page/testPage.jsf?name=SampleTop"
        imageURL="/resource/sample/images/sample.png"
        >
    <sun:treeNode 
            id="treeNodeBB"
            text="SampleBB"
            url="/sample/page/testPage.jsf?name=SampleBB"
            imageURL="resource/sample/images/sample.png" />
</sun:treeNode>

This file uses the sun:treenode tag to specify both a top-level tree node and another node nested beneath it. In your own JavaServer Faces pages, specify the attributes of this tag as follows:

id

A unique identifier for the tree node.

text

The node name that appears in the tree.

url

The location of the JavaServer Faces page that appears when you click the node. In the example, most of the integration points use a very simple JavaServer Faces page called testPage.jsf, which is in the src/main/resources/page/ directory. Specify the integration point id value as the root of the URL; in this case, it is sample (see Specifying the ID of an Add-On Component). The rest of the URL is relative to the src/main/resources/ directory, where sampleNode.jsf resides.

The url tag in this example passes a name parameter to the JavaServer Faces page.

imageURL

The location of a graphic to display next to the node name. In the example, the graphic is always sample.png, which is in the src/main/resources/images/ directory. The URL for this image is an absolute path, /resource/sample/images/sample.png, where sample in the path is the integration point id value (see Specifying the ID of an Add-On Component).

Adding Tabs to a Page

You can add a tab to an existing tab set, or you can create a tab set for your own page. One way to add a tab or tab set is to use an integration point of type org.glassfish.admingui:serverInstTab, which adds a tab to the tab set on the main GlassFish Server page of the Administration Console. You can also create sub-tabs. Once again, the parentId element specifies where to place the tab or tab set.

Example 3-4 Example Tab Integration Point

In the example, the following integration-point element adds a new tab on the main GlassFish Server page of the Administration Console:

        <integration-point 
            id="sampleTab"
            parentId="serverInstTabs"
            type="org.glassfish.admingui:serverInstTab" 
            priority="500" 
            content="sampleTab.jsf"
        />

This example specifies the following values:

• The id value, sampleTab, specifies the integration point ID.

• The parentId value, serverInstTabs, specifies the tab set associated with the server instance. The GlassFish Server page is the only one of the default Administration Console pages that has a tab set.

• The type value, org.glassfish.admingui:serverInstTab, specifies the integration point type as a tab associated with the server instance.

• The priority value, 500, specifies the order of the tab within the tab set. This value is optional.

• The content value, sampleTab.jsf, specifies the JavaServer Faces page that displays the tab.

Example 3-5 Example Tab Set Integration Points

The following integration-point elements add a new tab with two sub-tabs, also on the main GlassFish Server page of the Administration Console:

        <integration-point 
            id="sampleTabWithSubTab"
            parentId="serverInstTabs"
            type="org.glassfish.admingui:serverInstTab" 
            priority="300" 
            content="sampleTabWithSubTab.jsf"
        />
        
        <integration-point 
            id="sampleSubTab1" 
            parentId="sampleTabWithSubTab"
            type="org.glassfish.admingui:serverInstTab" 
            priority="300" 
            content="sampleSubTab1.jsf"
        />
        <integration-point 
            id="sampleSubTab2" 
            parentId="sampleTabWithSubTab"
            type="org.glassfish.admingui:serverInstTab" 
            priority="400" 
            content="sampleSubTab2.jsf"
        />

These examples specify the following values:

• The id values, sampleTabWithSubTab, sampleSubTab1, and sampleSubTab2, specify the integration point IDs for the tab and its sub-tabs.

• The parentId of the new tab, serverInstTabs, specifies the tab set associated with the server instance. The parentId of the two sub-tabs, sampleTabWithSubTab, is the id value of this new tab.

• The type value, org.glassfish.admingui:serverInstTab, specifies the integration point type for all the tabs as a tab associated with the server instance.

• The priority values specify the order of the tabs within the tab set. This value is optional. In this case, the priority value for sampleTabWithSubTab is 300, which is higher than the value for sampleTab. That means that sampleTabWithSubTab appears to the left of sampleTab in the Administration Console. The priority values for sampleSubTab1 and sampleSubTab2 are 300 and 400 respectively, so sampleSubTab1 appears to the left of sampleSubTab2.

• The content values, sampleTabWithSubTab.jsf, sampleSubTab1.jsf, and sampleSubTab2.jsf, specify the JavaServer Faces pages that display the tabs.

Creating JavaServer Faces Pages for Your Tabs

A JavaServer Faces page for a tab uses the tag sun:tab. This tag provides all the capabilities of the Project Woodstock tag webuijsf:tab.

Example 3-6 Example JavaServer Faces Page for a Tab

In the example, the sampleTab.jsf file has the following content:

<sun:tab id="sampleTab" immediate="true" text="Sample First Tab">
    <!command
        setSessionAttribute(key="serverInstTabs" value="sampleTab");
        gf.redirect(page="#{request.contextPath}/page/tabPage.jsf?name=Sample%20First%20Tab");
    />
</sun:tab>

In your own JavaServer Faces pages, specify the attributes of this tag as follows:

id

A unique identifier for the tab, in this case sampleTab.

immediate

If set to true, event handling for this component should be handled immediately (in the Apply Request Values phase) rather than waiting until the Invoke Application phase.

text

The tab name that appears in the tab set.

The JSF page displays tab content differently from the way the page for a node displays node content. It invokes two handlers for the command event: setSessionAttribute and gf.redirect. The gf.redirect handler has the same effect for a tab that the url attribute has for a node. It navigates to a simple JavaServer Faces page called tabPage.jsf, in the src/main/resources/page/ directory, passing the text “Sample First Tab” to the page in a name parameter.

The sampleSubTab1.jsf and sampleSubTab2.jsf files are almost identical to sampleTab.jsf. The most important difference is that each sets the session attribute serverInstTabs to the base name of the JavaServer Faces file that corresponds to that tab:

setSessionAttribute(key="serverInstTabs" value="sampleTab");

setSessionAttribute(key="serverInstTabs" value="sampleSubTab1");

setSessionAttribute(key="serverInstTabs" value="sampleSubTab2");

Adding a Task to the Common Tasks Page

You can add either a single task or a group of tasks to the Common Tasks page of the Administration Console. To add a task or task group, use an integration point of type org.glassfish.admingui:commonTask.

See Adding a Task Group to the Common Tasks Page for information on adding a task group.

Example 3-7 Example Task Integration Point

In the example console-config.xml file, the following integration-point element adds a task to the Deployment task group:

        <integration-point 
                id="sampleCommonTask" 
                parentId="deployment"
                type="org.glassfish.admingui:commonTask" 
                priority="200"
                content="sampleCommonTask.jsf"
        />

This example specifies the following values:

• The id value, sampleCommonTask, specifies the integration point ID.

• The parentId value, deployment, specifies that the task is to be placed in the Deployment task group.

• The type value, org.glassfish.admingui:commonTask, specifies the integration point type as a common task.

• The priority value, 200, specifies the order of the task within the task group.

• The content value, sampleCommonTask.jsf, specifies the JavaServer Faces page that displays the task.

Creating a JavaServer Faces Page for Your Task

A JavaServer Faces page for a task uses the tag sun:commonTask. This tag provides all the capabilities of the Project Woodstock tag webuijsf:commonTask.

Example 3-8 Example JavaServer Faces Page for a Task

In the example, the sampleCommonTask.jsf file has the following content:

<sun:commonTask
        text="Sample Application Page"
        toolTip="Sample Application Page"
        onClick="return admingui.woodstock.commonTaskHandler('treeForm:tree:applications:ejb', 
        '#{request.contextPath}/sample/page/testPage.jsf?name=Sample%20Application%20Page');">
</sun:commonTask>

This file uses the sun:commonTask tag to specify the task. In your own JavaServer Faces pages, specify the attributes of this tag as follows:

text

The task name that appears on the Common Tasks page.

toolTip

The text that appears when a user places the mouse cursor over the task name.

onClick

Scripting code that is to be executed when a user clicks the task name.

Adding a Task Group to the Common Tasks Page

You can add a new group of tasks to the Common Tasks page to display the most important tasks for your add-on component. To add a task group, use an integration point of type org.glassfish.admingui:commonTask.

Example 3-9 Example Task Group Integration Point

In the example console-config.xml file, the following integration-point element adds a new task group to the Common Tasks page:

       <integration-point 
            id="sampleGroup" 
            parentId="commonTasksSection"
            type="org.glassfish.admingui:commonTask" 
            priority="500"
            content="sampleTaskGroup.jsf"
        />

This example specifies the following values:

• The id value, sampleGroup, specifies the integration point ID.

• The parentId value, commonTasksSection, specifies that the task group is to be placed on the Common Tasks page.

• The type value, org.glassfish.admingui:commonTask, specifies the integration point type as a common task.

• The priority value, 500, specifies the order of the task group on the Common Tasks page. The low value places it at the end of the page.

• The content value, sampleTaskGroup.jsf, specifies the JavaServer Faces page that displays the task.

Creating a JavaServer Faces Page for Your Task Group

A JavaServer Faces page for a task group uses the tag sun:commonTasksGroup. This tag provides all the capabilities of the Project Woodstock tag webuijsf:commonTasksGroup.

Example 3-10 Example JavaServer Faces Page for a Task Group

In the example, the sampleTaskGroup.jsf file has the following content:

<sun:commonTasksGroup title="My Own Sample Group">
    <sun:commonTask
            text="Go To Sample Resource"
            toolTip="Go To Sample Resource"
            onClick="return admingui.woodstock.commonTaskHandler('form:tree:resources:treeNode1', 
            '#{request.contextPath}/sample/page/testPage.jsf?name=Sample%20Resource%20Page');">
    </sun:commonTask>
    <sun:commonTask
            text="Sample Configuration"
            toolTip="Go To Sample Configuration"
            onClick="return admingui.woodstock.commonTaskHandler('form:tree:configuration:sampleConfigNode', 
            '#{request.contextPath}/sample/page/testPage.jsf?name=Sample%20Configuration%20Page');">
    </sun:commonTask>
</sun:commonTasksGroup>

This file uses the sun:commonTasksGroup tag to specify the task group, and two sun:commonTask tags to specify the tasks in the task group. The sun:commonTasksGroup tag has only one attribute, title, which specifies the name of the task group.

Adding Content to a Page

You can add content for your add-on component to an existing top-level page, such as the Configuration page or the Resources page. To add content to one of these pages, use an integration point of type org.glassfish.admingui:configuration or org.glassfish.admingui:resources.

Example 3-11 Example Resources Page Implementation Point

In the example console-config.xml file, the following integration-point element adds new content to the top-level Resources page:

        <integration-point 
                id="sampleResourceLink"
                parentId="propSheetSection"
                type="org.glassfish.admingui:resources" 
                priority="100" 
                content="sampleResourceLink.jsf"
        />

This example specifies the following values:

• The id value, sampleResourceLink, specifies the integration point ID.

• The parentId value, propSheetSection, specifies that the content is to be a section of a property sheet on the page.

• The type value, org.glassfish.admingui:resources, specifies the integration point type as the Resources page.

  To add content to the Configuration page, specify the type value as org.glassfish.admingui:configuration.

• The priority value, 100, specifies the order of the content on the Resources page. The high value places it at the top of the page.

• The content value, sampleResourceLink.jsf, specifies the JavaServer Faces page that displays the new content on the Resources page.

Another integration-point element in the console-config.xml file places similar content on the Configuration page.

Creating a JavaServer Faces Page for Your Page Content

A JavaServer Faces page for page content often uses the tag sun:property to specify a property on a property sheet. This tag provides all the capabilities of the Project Woodstock tag webuijsf:property.

Example 3-12 Example JavaServer Faces Page for a Resource Page Item

In the example, the sampleResourceLink.jsf file has the following content:

<sun:property>
    <sun:hyperlink 
        toolTip="Sample Resource" 
        url="/sample/page/testPage.jsf?name=Sample%20Resource%20Page" >
        <sun:image url="/resource/sample/images/sample.png" />
        <sun:staticText text="Sample Resource" />
    </sun:hyperlink>
</sun:property>

<sun:property>
    <sun:hyperlink 
        toolTip="Another" 
        url="/sample/page/testPage.jsf?name=Another" >
        <sun:image url="/resource/sample/images/sample.png" />
        <sun:staticText text="Another" />
    </sun:hyperlink>
</sun:property>

The file specifies two simple properties on the property sheet, one above the other. Each consists of a sun:hyperlink element (a link to a URL). Within each sun:hyperlink element is nested a sun:image element, specifying an image, and a sun:staticText element, specifying the text to be placed next to the image.

Each sun:hyperlink element uses a toolTip attribute and a url attribute. Each url attribute references the testPage.jsf file that is used elsewhere in the example, specifying different content for the name parameter.

You can use many other kinds of user interface elements within a sun:property element.

Adding a Page to the Administration Console

Your add-on component may require new configuration tasks. In addition to implementing commands that accomplish these tasks (see Chapter 4, Extending the asadmin Utility), you can provide property sheets that enable users to configure your component or to perform tasks such as creating and editing resources for it.

Example 3-13 Example JavaServer Faces Page for a Property Sheet

Most of the user interface features used in the example reference the file testPage.jsf or (for tabs) the file tabPage.jsf. Both files are in the src/main/resources/page/ directory. The testPage.jsf file looks like this:

<!composition template="/templates/default.layout" guiTitle="TEST Sample Page Title">
<!define name="content">
<sun:form id="propertyForm">
            
<sun:propertySheet id="propertySheet">
    <sun:propertySheetSection id="propertySection">
       <sun:property id="prop1" labelAlign="left" noWrap="true" 
                     overlapLabel="false" label="Test Page Name:" >
            <sun:staticText text="$pageSession{pageName}" >
                <!beforeCreate
                    getRequestValue(key="name" value=>$page{pageName});
                />
            </sun:staticText>
        </sun:property>
    </sun:propertySheetSection>
</sun:propertySheet>
<sun:hidden id="helpKey" value="" />

</sun:form>
</define>
</composition>

The page uses the composition directive to specify that the page uses the default.layout template and to specify a page title. The page uses additional directives, events, and tags to specify its content.