Declarative Menus

Declarative menus are used to add new or customize default navigation elements in displayed portal pages. These PSML declarations are part of the page and folder elements. As with other PSML elements, effective menu declarations available for a given page are those that are explicity defined in the page along with all defined in parent folders. For this reason, global site menus are defined in the PSML associated with the site root folder. Menu definitions in a specific page or folder override menus with the same name found in parent folders.

Portal layout decorators access page menu declarations by name while rendering portal content. Menus are used to create dynamic navigation panes, portal page tabs, bread crumb links, and pull downs. The Portal Site Component is responsible for fleshing out the dynamic menu definition options with page specific PSML elements from the site. For instance, a global menu declaration would typically be involved in the following sequence of events while a portal page is being composed:

1. The portal layout decorator would request a menu definition by name,
2. the definition would be inherited by the current page and located in the root folder PSML,
3. the Portal Site Component would interpret the menu definition in the context of the current page and populate page, folder, and link menu options,
4. the decorator would display the menu rendering titles and text from the menu definition itself and the computed menu options into portal navigation content.

There are default global menu declarations supported internally by the Portal Site Component that do not need to be explicitly defined in any page or folder PSML elements of the site:

• pages: relative pages menu used to define the page tabs above the portal.
• breadcrumbs: paths to page used to provide history links below the page tabs.
• navigations: relative subfolders and root level links menu used to define the navigation pane beside the portal.
• back: parent folder menu used to define the single "back" link above the portal page tabs.

The remainder of this guide provides more information on specifying and using declarative menu definitions within Jetspeed2:

• Menu Definition
• Options
• Separator
• Include
• Exclude
• Page Layout Decorators
• Portal Site Component
• PSML Document DTDs

Menu Definition

The <menu> element defines a menu to be used by the layout decorators or a nested menu within another menu. There are many valid attributes for the menu element:

The <menu> element contains a number of other menu definition PSML elements. With the exception of the title and metadata elements, the relative order of these elements determines the order that the layout decorators present them:

Examples:

<!-- simple menu composed of 2 pages -->
<menu name="simple">
    <options>/some-top-page.psml,/custom/some-other-page.psml</options>
</menu>

<!-- site menu for the top 2 levels: folders result in nested menus -->
<menu name="top-2-levels" options="/" depth="2" skin="dhtml-pull-down"/>

<!-- menu containing top level elements profiled by roles -->
<menu name="top-role-pages" regexp="true" options="/*" profile="roles"/>

<!-- contrived example demonstrating element syntax -->
<menu name="top-custom">
    <title>Top Menu</title>
    <metadata name="title" xml:lang="fr">Haut</metadata>
    <options regexp="true" profile="groups">/group-pages/*</options>
    <menu options="/" profile="page">
        <separator>
            <text>-- Top Pages --</text>
            <title>Top Pages</title>
        </separator>
        <options regexp="true">/*</options>
        <separator>
            <title>Custom Pages</title>
        </separator>
        <options depth="2">/custom-folder/</options>
    </menu>
    <exclude>top-role-pages</exclude>
    <separator>More Top Pages</separator>
    <include nest="true">top-role-pages</include>
</menu>

The definitions for the default global menu declarations supported internally by the Portal Site Component:

<!-- standard pages tabs menu -->
<menu name="pages" regexp="true" options="*.psml"/>

<!-- standard history breadcrumbs menu -->
<menu name="breadcrumbs" options="~" paths="true"/>

<!-- standard navigations panel menu -->
<menu name="navigations">
  <separator>Folders</separator>
  <options regexp="true">./*/</options>
  <include>page-navigations</include>
  <separator>Additional Links</separator>
  <options regexp="true">/*.link</options>
</menu>

<!-- standard parent folder link menu -->
<menu name="back" options="../"/>

Note that the separator text of these definitions is localized internally.

Menu Options Definition

The <options> element defines a single or multiple options within a menu. The text of this simple element specifies document paths that yield page, folder, or link menu options. Paths specified in this element are Page URIs; these URIs may or may not directly reflect the folder and page hierarchy. The Portal Site Component maps these options paths to PSML folder and page elements. Multiple option paths can be specified as a comma separated list of paths and/or regular expression patterns. Relative paths are interpreted as relative to the current page. Special patterns, '~' or '@', can be used to reference the current page. This element shares many attributes in common with the menu element:

Example:

<menu>
    ...
    <options regexp="true" order="*.psml,*.link">/some-top-page.psml,/custom/some-other-page.psml,/*.link</options>
    ...
</menu>

Menu Separator Definition

The <separator> element defines a separator to be included in a menu. The separator will be included only if options or nested menus appear below this element within a menu definition. The text of the separator can be specified in the contained text of this element or in the text menu definition element. There is only one attribute accepted by the separator element:

The <separator> element contains a number of other menu definition PSML elements:

Examples:

<menu>
    ...
    <separator>-------------</separator>
    ...
    <separator>
        <text>-- Top 10 Pages --</text>
        <metadata name="text" xml:lang="fr">Haut Pages</metadata>
        <title>Top 10 pages as voted by the Jetspeed2 users!</title>
    </separator>
    ...
</menu>

Menu Include Definition

The <include> element includes options or nested menus from another menu. The name of the menu to include is specified as the text value of this element. There is only one valid attribute for the include element:

Examples:

<menu>
    ...
    <include nest="true">navigations</include>
    ...
</menu>

Menu Exclude Definition

The <exclude> element excludes options or nested menus from another menu. This option is used primarily to remove menu options that already appear on the portal page in another menu from this menu. Matching options or menus will be excluded only if they appear above this element within a menu definition. The name of the menu to include is specified as the text value of this simple element.

Examples:

<menu>
    ...
    <exclude>pages</exclude>
    ...
</menu>

Page Layout Decorators

The page layout decorators request menus from the Portal Site Component when the page is being rendered in the Jetspeed2 pipeline. The decorators expect certain menus to be provided by the PSML declarations. Before custom menus can be displayed in the portal, the decorators need to be modified to render the custom menu. Here is an example taken from a Velocity layout decorator header.vm file:

...
#set($pagesStandardMenu = $site.getMenu("pages"))
#if(!$pagesStandardMenu.empty)
  <div class="tabs">
#includeTabsNavigation($pagesStandardMenu $LEFT_TO_RIGHT)
  </div>
#end
...

This code block renders the standard pages tabs menu within a portal page. The Portal Site Component is exposed as the $site Velocity context variable. The test for an empty menu definition is designed to ensure that empty menus are not rendered into the page content. Finally, a decorator macro is executed to expand the menu content. This approach is taken in general to support the rendering of nested menus with recursive invocations of the macro. In this case, the decorator is expecting only page options. Here is the macro implementation used to render the pages tabs menu:

#macro (includeTabsNavigation $_menu $_orientation)
  <table border="0" cellpadding="0" cellspacing="0">
  <tr>
    #foreach($element in $_menu.elements.iterator())
      #if($element.elementType == "option")
        #set($tabTitle = $element.getTitle($preferedLocale))
        #set($tabName = $element.getShortTitle($preferedLocale))
        #if($_orientation == $LEFT_TO_RIGHT)
          #if($element.isSelected($site))
            <td class="LTabLeft" nowrap="true">&nbsp;</td>
            <td class="LTab" align="center" valign="middle" nowrap="true" title="$!tabTitle">${tabName}</td>
            <td class="LTabRight"  nowrap="true">&nbsp;</td>
          #else
            #set($tabUrl = $jetspeed.getAbsoluteUrl($element.url))
            <td class="LTabLeftLow"  nowrap="true">&nbsp;</td>
            <td class="LTabLow" align="center" valign="middle" nowrap="true" title="$!tabTitle"><a href="$tabUrl">${tabName}</a></td>
            <td class="LTabRightLow"  nowrap="true">&nbsp;</td>
          #end
        #end
      #end
    #end
  </tr>
  </table>
#end

This macro iterates over the computed page menu options supplied by the Portal Site Component, rendering a series of table data HTML elements that make up each displayed tab. The whole menu is rendered as a HTML table with a single row.

The declarative menu Portal Site Component objects exposed to the layout decorators are documented in the Jetspeed API. Here is a list of the primary interfaces that make up this interface:

• org.apache.jetspeed.portalsite.Menu
• org.apache.jetspeed.portalsite.MenuElement
• org.apache.jetspeed.portalsite.MenuOption
• org.apache.jetspeed.portalsite.MenuSeparator
• org.apache.jetspeed.portalsite.PortalSiteRequestContext

Jetspeed2 provides many sample decorators including those that will render tabs, navigation panes with nested submenus, history breadcrumb links, and even DHTML JSCookMenu nested pulldown menus... all from the declarative menu elements documented here.

Portal Site Component

In conjunction with the Jetspeed Profiler Component, the Portal Site Component performs two closely related functions:

1. Map portal request URLs from a user to PSML page or folder elements in the site, and
2. construct site navigational menus and their options that reflect what is available to the user from the site.

Menu definition options paths are specified as Page URIs to leverage this mapping functionality. A Page URI is essentially the tail portion of a portal request URL that is used to address a page or folder. Using Page URIs for options allows menu definitions to be shared by all users of the portal: the user specific profile and effective security constraints are applied to generate the menu options. This implies that the physical paths used internally within the Page Manager file system or database cannot be specified to directly address a specific PSML element.

For example, suppose the following:

• the default "j2" profiling rules are in effect for the 'someone' user,
• the following physical PSML site structure is available in the Page Manager,
• .../page0.psml
• .../page1.psml
• .../page2.psml
• .../hidden-page0.psml
• .../_user/someone/page0.psml
• security constraints denied access to '/page2.psml' for the user, and
• '/hidden-page.psml' is declared hidden in the page PSML.

• Menu options attempting to use invalid Page URIs are ignored. Invalid URIs include those containing reserved folders such as '_user', '_role', etc. or other physical paths specific to the the Page Manager implementation.
• Security constrained pages or folders cannot be referenced by requests and will not appear in menus.
• Hidden pages and/or folders can be requested, but are not visible in menus. There is one exception for pages: a hidden page is considered visible if it is the request page.