01 Administration Navigation Channel

Owned by John Fereira
Last updated: Apr 26, 2007 by Andrew PetroVersion comment
6 min read

Administration Navigation Channel

Contents

What is the Administration Navigation Channel
Registering Links
Pluggability of User Interface (Tree anyone?)
List Model's static links file: adminNav.xml
Adding a Static Link
Registering Links Via CAR Descriptors

01 Administration Navigation Channel

When an administrator uses the portal, channels meant solely for administrators have shown up traditionally in two different ways. Prior to uPortal 2.6, the 'Channel Admin' link presented the administrator with links to 'Publish a new channel' or 'Modify a currently published channel'. Additionally, depending on how the portal instance is configured there may be an 'Admin Tools' tab pushed into the layout of an administrator. The Admin Nav channel takes the place of rendering the links presented when the 'Channel Admin' link is selected. Previously, this list was provided by the Channel Manager channel. Now it is a standalone, runtime-extensible channel to which links can be added without bloating the channel manager channel with unrelated functionality. Furthermore, unlike the fixed set of channel available on the 'Admin Tools' tab, this channel dynamically alters the list of available links it presents based on the authorizations had by its current user.

01 Administration Navigation Channel

One of the key benefits of the Admin Nav channel is that links can now be added to this area without bloating the channel manager channel with unrelated functionality. Links are added to Admin Nav dynamically at any time after the web server has started up and are not persisted. This means that they must be registered each time that the server starts up. This was done intentionally so that when applications are removed from the portal their administrative links are also removed. To register a link, code must use an implementation of org.jasig.portal.channels.adminnav.ILinkRegistrar. An instance of this interface is acquired by calling a static method on the Admin Nav Channel. The following code snippet shows how links are added. Each step and piece used during registration will be explained.

    ILinkRegistrar reg = AdminNavChannel.getLinkRegistrar();
    Map parms = new HashMap();
    // add parms as needed
    reg.addLink("<fname Of Channel>", "<lable ID of link>", <ILabelResolver instance>, parms);

Such registration can take place via a static initializer or a constructor. As will be shown below, such registrations can also be initiated via a declaration in a CAR deployment descriptor or via a the properties/adminNav.xml configuration file depending on Admin Nav's configuration. As can be seen, the addLink method takes four parameters:

Fname

The functional name, or fname, of a channel can be defined during publishing. If specified during publishing, the channel can later be instantiated and brought into focus mode in the portal using a special URL if the user has permission to subscribe to that channel. This is true even if that channel does not exist in the user's layout. The fname passed-in when registering a link is used to create one of these special URL as the target for the resulting link that appears in Admin Nav. When one of these links is selected, the channel represented by that functional name will be brought into focus.

Label ID and ILabelResolver

The label ID is used to localized the label of the registered link. This ID is passed to the passed-in implementation of ILabelResolver to acquire a localized version of the label for the link whenever Admin Nav regenerates its list. Accordingly, all label ids to be passed to a specific ILabelResolver implementation must be unique within that scope.

Parameter Map

The parameter map is meant to be used for name and value pairs suitable for appending to the link's URL as query parameters. Although this is the intended use their interpretation is completely defined by Admin Nav's plugged-in internal implementation to be discussed next. The default internal implementation provided with Admin Nav allows the map to be an optional parameter. For this internal implementation a value of null can safely be passed for the map when registering a link.

01 Administration Navigation Channel

Technically speaking, Admin Nav is not a full fledged channel on its own. It is a wrapper around an implementation that provides its visual representation. Any class that implements org.jasig.portal.channels.adminnav.INavigationModel can be used. A default implementation is provided that presents the links in list form sorted by link label. The implementation to be used is specified using the following portal.properties definition.

    org.jasig.portal.channels.adminnav.AdminNavigation.implementation
      = org.jasig.portal.channels.adminnav.provider.ListModel

As can be seen, the default implementation is provided by the ListModel class. Since Admin Nav is designed to be pluggable, any user interface could be provided to present these links. For example, a hierarchically organized tree could be used to group related links by administrative area like channel administration versus internal cache administration. Since the implementation defines how the parameter map is used it could also define prefixes to map keys that indicated the parameter was not to be used as a query parameter but defined what portion of the tree the link should be placed under.

01 Administration Navigation Channel

In addition to accepting dynamic registrations of links, the reference implementation, ListModel, also looks for links defined statically via a configuration file in the properties directory. The name of the file is adminNav.xml. Upon instantiation, ListModel uses two other utility classes provided with AdminNav to load these statically defined links. And instance of ResourceBundleResolver is instantiated pointed at '/properties/adminNav'. This provides an instance of ILabelResolver that will look for resource bundles with that base name for the current locale of the user.

For example, the reference implementation provides two property resource bundle files in the properties directory to resolve the labels defined in adminNav.xml. The first is 'adminNav.properties' which defines the base bundle which will be used if no locale or language specific version is located. The second is 'adminNav_de_DE.properties' to showcase labels rendering in German if the German locale is selected. However, this is only meant as sample file and at the time of this writing did not contain actual German versions of the labels.

The ResourceBundleProvider instance is then passed to an instance of XMLLinksFileLoader along with the path to adminNav.xml. XMLLinksFileLoader loads an XML file using an instance of XMLLinksHandler which defines the structure found in adminNav.xml and is responsible for making the calls to register the links found there-in. Copious comments are include in adminNav.xml explaining the XML structure that should be used when defining static links. Remember: for each link registered the appropriate entries should be added to the resource bundles that will provide the locale specific versions of the labels for those links.

01 Administration Navigation Channel

As an example, lets add the Number Guessing Game to the list of links that appear in Admin Nav. Using the Channel Manager channel we look at the publishing information for Number Guessing Game. It has a functional name of 'number-guessing-game'. Furthermore, since the labels for ListModel come from adminNav.properties and its derivative property resource bundles we'll use a lable id that does not conflict with any other keys in those property files, say 'NUMBER_GUESSING_GAME'. Following the comments in properties/adminNav.xml we add the following declaration:

    <link labelId="NUMBER_GUESSING_GAME" channelFunctionalName="number-guessing-game"/>

To the base property file adminNav.properties we'll add the following label declaration.

    NUMBER_GUESSING_GAME=Number Guessing Game

To the German version of this property resource bundle, adminNav_de_DE.properties, we'll add the following label declaration.

    NUMBER_GUESSING_GAME=Nummer-Erraten-Spiel

After saving all three files, re-deploying, and restarting the web server the Number Guessing Game link now appears and presents and appropriate lable for both the English and German locales.

01 Administration Navigation Channel

Looking back at XMLLinksHandler we see that it is an implementation of ContentHandler, it can be used in an extension block in a CAR deployment descriptor. When used in this manner a resource bundle resolver instance must be provided using an optional attribute of the outermost <links> element. The 'bundleResolver' attribute should hold the class resource path for a base resource bundle name that should be used to resolve registered link labels. This includes bundles located in CARs.

As an example, lets register the Number Guessing Game in the same manner as we did above but via a CAR deployment descriptor. Using the same lable id and functional name as before and knowing that there are resource bundles with a base bundle name of properties/adminNav we can construct a CAR with the following deployment descriptor. Each time the server starts up this descriptor will be processed and the link added again.

    <ext contentHandler="org.jasig.portal.channels.adminnav.XMLLinksHandler">
      <links bundleResolver="properties/adminNav">
        <link labelId="NUMBER_GUESSING_GAME" channelFunctionalName="number-guessing-game"/>
      </links>
    </ext>