type=page
status=published
title=Extending the Administration Console
next=extending-asadmin.html
prev=writing-hk2-components.html
~~~~~~
Extending the Administration Console
====================================

[[GSACG00003]][[ghmrb]]


[[extending-the-administration-console]]
3 Extending the Administration Console
--------------------------------------

The Administration Console is a browser-based tool for administering
Eclipse GlassFish Server. It features an easy-to-navigate interface and online
help. Extending the Administration Console enables you to provide a
graphical user interface for administering your add-on component. You
can use any of the user interface features of the Administration
Console, such as tree nodes, links on the Common Tasks page, tabs and
sub-tabs, property sheets, and Jakarta Server Faces pages. Your add-on
component implements a marker interface and provides a configuration
file that describes how your customizations integrate with the
Administration Console.

This chapter refers to a simple example called `console-sample-ip` that
illustrates how to provide Administration Console features for a
hypothetical add-on component. 

The following topics are addressed here:

* link:#ghmof[Administration Console Architecture]
* link:#ghmom[About Administration Console Templates]
* link:#ghmqr[About Integration Points]
* link:#ghmpg[Specifying the ID of an Add-On Component]
* link:#ghmpk[Adding Functionality to the Administration Console]
* link:#ghmqi[Adding Internationalization Support]
* link:#ghmqg[Changing the Theme or Brand of the Administration Console]
* link:#ghpkz[Creating an Integration Point Type]

[[ghmof]][[GSACG00097]][[administration-console-architecture]]

Administration Console Architecture
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Administration Console is a web application that is composed of OSGi
bundles. These bundles provide all the features of the Administration
Console, such as the Web Applications, Update Center, and Security
content. To provide support for your add-on component, create your own
OSGi bundle that implements the parts of the user interface that you
need. Place your bundle in the `modules` directory of your GlassFish
Server installation, along with the other Administration Console
bundles.

To learn how to package the Administration Console features for an
add-on component, go to the `modules` directory of your GlassFish Server
installation and examine the contents of the files named
`console-`componentname`-plugin.jar`. Place the `console-sample-ip`
project bundle in the same place to deploy it and examine the changes
that it makes to the Administration Console.

The Administration Console includes a Console Add-On Component Service.
The Console Add-On Component Service is an HK2 service that acts as a
façade to all theAdministration Console add-on components. The Console
Add-On Component Service queries the various console providers for
integration points so that it can perform the actions needed for the
integration (adding a tree node or a new tab, for example). The
interface name for this service is
`org.glassfish.api.admingui.ConsolePluginService`.

For details about the Hundred-Kilobyte Kernel (HK2) project, see
link:introduction.html#ghmnq[Hundred-Kilobyte Kernel] and
link:writing-hk2-components.html#ghokq[HK2 Component Model].

Each add-on component must contain a console provider implementation.
This is a Java class that implements the
`org.glassfish.api.admingui.ConsoleProvider` interface and uses the HK2
`@Service` annotation. The console provider allows your add-on component
to specify where your integration point configuration file is located.
This configuration file communicates to the Console Add-On Component
Service the customizations that your add-on component makes to the
Administration Console.

[[ghnzl]][[GSACG00187]][[implementing-a-console-provider]]

Implementing a Console Provider
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The `org.glassfish.api.admingui.ConsoleProvider` interface has one
required method, `getConfiguration`. The `getConfiguration` method
returns the location of the `console-config.xml` file as a
`java.net.URL`. If `getConfiguration` returns `null`, the default
location, `META-INF/admingui/console-config.xml`, is used. The
`console-config.xml` file is described in link:#ghmqr[About Integration
Points].

To implement the console provider for your add-on component, write a
Java class that is similar to the following example.

[[GSACG00019]][[ghosz]]


Example 3-1 Example `ConsoleProvider` Implementation

This example shows a simple implementation of the `ConsoleProvider`
interface:

[source,oac_no_warn]
----
package org.glassfish.admingui.plugin;

import org.glassfish.api.admingui.ConsoleProvider;
import org.jvnet.hk2.annotations.Service;

import java.net.URL;

@Service
public class SamplePlugin implements ConsoleProvider {

    public URL getConfiguration() { return null; }
}
----

This implementation of `getConfiguration` returns null to specify that
the configuration file is in the default location. If you place the file
in a nonstandard location or give it a name other than
`console-config.xml`, your implementation of `getConfiguration` must
return the URL where the file can be found.


[[ghmom]][[GSACG00098]][[about-administration-console-templates]]

About Administration Console Templates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

GlassFish Server includes a set of templates that make it easier to
create Jakarta Server Faces pages for your add-on component. These templates
use Templating for Jakarta Server Faces Technology, which is also known as
JSFTemplating.

Examples of JSFTemplating technology can be found in the following
sections of this chapter:

* link:#ghoej[Creating a Jakarta Server Faces Page for Your Node]
* link:#ghovg[Creating Jakarta Server Faces Pages for Your Tabs]
* link:#ghoeu[Creating a Jakarta Server Faces Page for Your Task]
* link:#ghoya[Creating a Jakarta Server Faces Page for Your Task Group]
* link:#ghpao[Creating a Jakarta Server Faces Page for Your Page Content]
* link:#ghmqe[Adding a Page to the Administration Console]

[[ghmqr]][[GSACG00099]][[about-integration-points]]

About Integration Points
~~~~~~~~~~~~~~~~~~~~~~~~

The integration points for your add-on component are the individual
Administration Console user interface features that your add-on
component will extend. You can implement the following kinds of
integration points:

* Nodes in the navigation tree
* Elements on the Common Tasks page of the Administration Console
* Jakarta Server Faces pages
* Tabs and sub-tabs

Specify all the integration points in a file named `console-config.xml`.
In the example, this file is in the directory
`project/src/main/resources/META-INF/admingui/`. The following sections
describe how to create this file.

In addition, create Jakarta Server Faces pages that contain JSF code
fragments to implement the integration points. In the example, these
files are in the directory `project/src/main/resources/`. The content of
these files depends on the integration point you are implementing. The
following sections describe how to create these JavaServer Faces pages.

For reference information on integration points, see
link:integration-point-reference.html#ghmrp[Integration Point Reference].

[[ghmpg]][[GSACG00100]][[specifying-the-id-of-an-add-on-component]]

Specifying the ID of an Add-On Component
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The `console-config.xml` file consists of a `console-config` element
that encloses a series of `integration-point` elements. The
`console-config` element has one attribute, `id`, which specifies a
unique name or ID value for the add-on component.

In the example, the element is declared as follows:

[source,oac_no_warn]
----
<console-config id="sample">
    ...
</console-config>
----

You will also specify this ID value when you construct URLs to images,
resources and pages in your add-on component. See link:#ghocf[Adding a
Node to the Navigation Tree] for an example.

For example, a URL to an image named `my.gif` might look like this:

[source,oac_no_warn]
----
<sun:image url="/resource/sample/images/my.gif" />
----

The URL is constructed as follows:

* `/resource` is required to locate any resource URL.
* `sample` is the add-on component ID. You must choose a unique ID
value.
* `images` is a folder under the root of the add-on component JAR file.

[[ghmpk]][[GSACG00101]][[adding-functionality-to-the-administration-console]]

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


[width="100%",cols="<100%",]
|=======================================================================
a|
Note:

The order in which these attributes are specified does not matter, and
in the example `console-config.xml` file the order varies. To improve
readability, this chapter uses the same order throughout.

|=======================================================================


The following topics are addressed here:

* link:#ghocf[Adding a Node to the Navigation Tree]
* link:#ghotv[Adding Tabs to a Page]
* link:#ghmqw[Adding a Task to the Common Tasks Page]
* link:#ghozn[Adding a Task Group to the Common Tasks Page]
* link:#ghmrg[Adding Content to a Page]
* link:#ghmqe[Adding a Page to the Administration Console]

[[ghocf]][[GSACG00188]][[adding-a-node-to-the-navigation-tree]]

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


[width="100%",cols="<100%",]
|=======================================================================
a|
Note:

The `webContainer` and `httpService` nodes are available only if you
installed the web container module for the Administration Console (the
`console-web-gui.jar` OSGi bundle).

|=======================================================================


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

[[GSACG00020]][[ghpmb]]


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.

[source,oac_no_warn]
----
        <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.

[[ghoej]][[GSACG00158]][[creating-a-javaserver-faces-page-for-your-node]]

Creating a Jakarta Server Faces Page for Your Node
++++++++++++++++++++++++++++++++++++++++++++++

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

[[GSACG00021]][[ghpmn]]


Example 3-3 Example Jakarta Server Faces Page for a Tree Node

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

[source,oac_no_warn]
----
<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 Jakarta Server 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
  link:#ghmpg[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
  Jakarta Server 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
  link:#ghmpg[Specifying the ID of an Add-On Component]).

[[ghotv]][[GSACG00189]][[adding-tabs-to-a-page]]

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.

[[GSACG00022]][[ghplc]]


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:

[source,oac_no_warn]
----
        <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 Jakarta Server Faces
page that displays the tab.

[[GSACG00023]][[ghplu]]


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:

[source,oac_no_warn]
----
        <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 Jakarta Server Faces pages that display
the tabs.

[[ghovg]][[GSACG00159]][[creating-javaserver-faces-pages-for-your-tabs]]

Creating Jakarta Server Faces Pages for Your Tabs
+++++++++++++++++++++++++++++++++++++++++++++

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

[[GSACG00024]][[ghpnt]]


Example 3-6 Example Jakarta Server Faces Page for a Tab

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

[source,oac_no_warn]
----
<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>
----


[width="100%",cols="<100%",]
|======================================================================
a|
Note:

In the actual file there are no line breaks in the `gf.redirect` value.

|======================================================================


In your own Jakarta Server 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 Jakarta Server 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
Jakarta Server Faces file that corresponds to that tab:

[source,oac_no_warn]
----
setSessionAttribute(key="serverInstTabs" value="sampleTab");

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

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

[[ghmqw]][[GSACG00190]][[adding-a-task-to-the-common-tasks-page]]

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 link:#ghozn[Adding a Task Group to the Common Tasks Page] for
information on adding a task group.

[[GSACG00025]][[ghpox]]


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:

[source,oac_no_warn]
----
        <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.

[[ghoeu]][[GSACG00160]][[creating-a-javaserver-faces-page-for-your-task]]

Creating a Jakarta Server Faces Page for Your Task
++++++++++++++++++++++++++++++++++++++++++++++

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

[[GSACG00026]][[gjkgd]]


Example 3-8 Example Jakarta Server Faces Page for a Task

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

[source,oac_no_warn]
----
<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>
----


[width="100%",cols="<100%",]
|=======================================================================
a|
Note:

In the actual file, there is no line break in the `onClick` attribute
value.

|=======================================================================


This file uses the `sun:commonTask` tag to specify the task. In your own
Jakarta Server 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.

[[ghozn]][[GSACG00191]][[adding-a-task-group-to-the-common-tasks-page]]

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

[[GSACG00027]][[ghplk]]


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:

[source,oac_no_warn]
----
       <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.

[[ghoya]][[GSACG00161]][[creating-a-javaserver-faces-page-for-your-task-group]]

Creating a Jakarta Server Faces Page for Your Task Group
++++++++++++++++++++++++++++++++++++++++++++++++++++

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

[[GSACG00028]][[ghpqe]]


Example 3-10 Example Jakarta Server Faces Page for a Task Group

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

[source,oac_no_warn]
----
<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>
----


[width="100%",cols="<100%",]
|=======================================================================
a|
Note:

In the actual file, there are no line breaks in the `onClick` attribute
values.

|=======================================================================


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.

[[ghmrg]][[GSACG00192]][[adding-content-to-a-page]]

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

[[GSACG00029]][[ghpnu]]


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:

[source,oac_no_warn]
----
        <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.

[[ghpao]][[GSACG00162]][[creating-a-javaserver-faces-page-for-your-page-content]]

Creating a Jakarta Server Faces Page for Your Page Content
++++++++++++++++++++++++++++++++++++++++++++++++++++++

A Jakarta Server 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`.

[[GSACG00030]][[ghpoz]]


Example 3-12 Example Jakarta Server Faces Page for a Resource Page Item

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

[source,oac_no_warn]
----
<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.

[[ghmqe]][[GSACG00193]][[adding-a-page-to-the-administration-console]]

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
link:extending-asadmin.html#ghmrd[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.

[[GSACG00031]][[ghple]]


Example 3-13 Example Jakarta Server 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:

[source,oac_no_warn]
----
<!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.

[[ghmqi]][[GSACG00102]][[adding-internationalization-support]]

Adding Internationalization Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To add internationalization support for your add-on component to the
Administration Console, you can place an event and handler like the
following at the top of your page:

[source,oac_no_warn]
----
<!initPage
    setResourceBundle(key="yourI18NKey" bundle="bundle.package.BundleName")
/>
----

Replace the values `yourI18NKey` and `bundle.package.BundleName` with
appropriate values for your component.

[[ghmqg]][[GSACG00103]][[changing-the-theme-or-brand-of-the-administration-console]]

Changing the Theme or Brand of the Administration Console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To change the theme or brand of the Administration Console for your
add-on component, use the integration point type
`org.glassfish.admingui:customtheme`. This integration point affects the
Cascading Style Sheet (CSS) files and images that are used in the
Administration Console.

[[GSACG00032]][[ghpls]]


Example 3-14 Example Custom Theme Integration Point

For example, the following integration point specifies a custom theme:

[source,oac_no_warn]
----
        <integration-point
                id="myownbrand"
                type="org.glassfish.admingui:customtheme"
                priority="2"
                content="myOwnBrand.properties"
        />
----

The `priority` attribute works differently when you specify it in a
branding integration point from the way it works in other integration
points. You can place multiple branding add-on components in the
`modules` directory, but only one theme can be applied to the
Administration Console. The `priority` attribute determines which theme
is used. Specify a value from 1 to 100; the lower the number, the higher
the priority. The integration point with the highest priority will be
used.

Additional integration point types also affect the theme or brand of the
Administration Console:

`org.glassfish.admingui:masthead`::
  Specifies the name and location of the include masthead file, which
  can be customized with a branding image. This include file will be
  integrated on the masthead of the Administration Console.
`org.glassfish.admingui:loginimage`::
  Specifies the name and location of the include file containing the
  branding login image code that will be integrated with the login page
  of the Administration Console.
`org.glassfish.admingui:loginform`::
  Specifies the name and location of the include file containing the
  customized login form code. This code also contains the login
  background image used for the login page for the Administration
  Console.
`org.glassfish.admingui:versioninfo`::
  Specifies the name and location of the include file containing the
  branding image that will be integrated with the content of the version
  popup window.

[[GSACG00033]][[ghpla]]


Example 3-15 Example of Branding Integration Points

For example, you might specify the following integration points. The
content for each integration point is defined in an include file.

[source,oac_no_warn]
----
       <integration-point
               id="myownbrandmast"
               type="org.glassfish.admingui:masthead"
               priority="80"
               content="branding/masthead.inc"
       />
       <integration-point
               id="myownbrandlogimg"
               type="org.glassfish.admingui:loginimage"
               priority="80"
               content="branding/loginimage.inc"
       />
       <integration-point
               id="myownbrandlogfm"
               type="org.glassfish.admingui:loginform"
               priority="80"
               content="branding/loginform.inc"
       />
       <integration-point
               id="myownbrandversinf"
               type="org.glassfish.admingui:versioninfo"
               priority="80"
               content="branding/versioninfo.inc"
       />
----

To provide your own CSS and images to modify the global look and feel of
the entire application (not just the Administration Console), use the
theming feature of https://github.com/eclipse-ee4j/glassfish-woodstock[Project
Woodstock] (`https://github.com/eclipse-ee4j/glassfish-woodstock`). Create a theme JAR
file with all the CSS properties and image files that are required by
your Woodstock component. Use a script provided by the Woodstock project
to clone an existing theme, then modify the files and properties as
necessary. Once you have created the theme JAR file, place it in the
`WEB-INF/lib` directory of the Administration Console so that the
Woodstock theme component will load the theme. In addition, edit the
properties file specified by your integration point
(`MyOwnBrand.properties`, for example) to specify the name and version
of your theme.

[[ghpkz]][[GSACG00104]][[creating-an-integration-point-type]]

Creating an Integration Point Type
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your add-on component provides new content that you would like other
people to extend, you may define your own integration point types. For
example, if you add a new page that provides tabs of monitoring
information, you might want to allow others to add their own tabs to
complement your default tabs. This feature enables your page to behave
like the existing Administration Console pages that you or others can
extend.

[[sthref4]][[to-create-an-integration-point-type]]

To Create an Integration Point Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1.  Decide on the name of your integration point type. +
The integration point type must be a unique identifier. You might use
the package name of your integration point, with a meaningful name
appended to the end, as in the following example: +
[source,oac_no_warn]
----
org.company.project:myMonitoringTabs
----
2.  After you have an integration point ID, use handlers to insert the
integration point implementation(s). +
Include code like the following below the place in your Jakarta Server Faces
page where you would like to enable others to add their integration
point implementations: +
[source,oac_no_warn]
----
<event>
    <!afterCreate
        getUIComponent(clientid="clientid:of:root"
                       component=>$attribute{rootComp});
        includeIntegrations(type="org.company.project:myMonitoringTabs"
                            root="#{rootComp}");
    />
</event>
----
Change `clientId:of:root` to match the `clientId` of the outermost
component in which you want others to be able to add their content (in
this example, the tab set is the most likely choice). Also include your
integration point ID in place of `org.company.project:myMonitoringTabs`.
If you omit the `root` argument to `includeIntegrations`, all components
on the entire page can be used for the `parentId` of the integration
points.


----