メニューの宣言

メニューの宣言は、表示されているポータルページに新しいナビゲーション要素を追加したり、デフォルトのものをカスタマイズしたりするために使われます。これらの PSML 宣言は、page 要素と folder 要素の一部分です。他の PSML 要素と同様に、メニュー宣言は、親フォルダで定義された全てに加えて、ページ内で明示的に定義されるものが有効となります。このため、グローバルなサイトのメニューは、サイトのルートフォルダに関連づけられている PSML ファイル内で定義されます。特定のページやフォルダのメニューの定義は、親フォルダで定義されている同じ名前のメニューを上書きします。

ポータルのレイアウトデコレータは、ポータルのコンテンツを描画しているときに、名前でページメニューの宣言にアクセスします。メニューは、動的なナビゲーションペインや、ポータルページのタブや、パンくずリストや、プルダウンメニューを作成するのに使われます。ポータルサイトコンポーネントは、サイトのページ固有の PSML エレメントを持つ動的なメニュー定義の選択肢を実際に形成することを担当しています。例えば、グローバルなメニュー定義は、一般的に、ポータルページが構成されている間、次のような順序でイベントに関係します。

  1. ポータルレイアウトデコレータは、名前でメニュー定義の要求を行います。
  2. 定義は、現在のページに継承され、ルートフォルダの PSML に設定されます。
  3. ポータルサイトコンポーネントは、現在のページのコンテキスト内のメニュー定義を解釈し、ページやフォルダやメニューの選択肢のリンクを設置します。
  4. デコレータは、メニュー定義自身と算出されたメニューの選択肢を元に、ポータルのナビゲーションコンテンツにタイトルとテキストを描画し、メニューを表示します。

ポータルサイトコンポーネントによって、内部的にサポートされた共通のメニュー定義が存在し、サイトのページやフォルダの PSML 要素に明示的には定義の必要がありません。

  • pages: ポータル上のページタブを定義するのに使われる、相対的なページメニュー。
  • bredcrumbs: ページタブ以下にリンクの履歴を提供するのに使われる、ページへのパス。
  • navigations: ポータルの横のナビゲーションパネルを定義するのに使われる、相対サブフォルダとルートレベルのリンクメニュー
  • back: ポータルページタブ上の、以前のページへ 1 つ戻るためのリンクを定義するのに使われる、親フォルダのメニュー。
メニュー定義内で構築されるこれらは、期待どおり、サイトの PSML 内で同じ名前で宣言されるメニューに上書きされます。

メニューの定義

<menu> 要素は、レイアウトデコレータもしくは他のメニュー内の階層化されたメニューによって使われるメニューを定義します。menu 要素には、たくさんの有効な属性が存在します。

属性説明
nameテンプレートコードおよび(または)メニュー参照からの検索のためのメニュー名を指定します。この属性は、トップレベルのノードで必須で、階層化されたメニューでは無視されます。
optionsメニューの指定に、ドキュメントとフォルダの深い階層が存在する場合、メニューのためのルートドキュメントのパスを指定します。この属性は、ページ、フォルダ、メニューの選択肢のリンクの指定を行うドキュメントパスも定義します。カンマで区切ったパスおよび (または) 正規表現のパターンを、複数のオプションパスとして指定可能です。相対パスは、現在のページからの相対パスとして解釈されます。「~」や「@」といった特別なパターンを、現在のページを参照するために使うことができます。
depthオプションフォルダからのドキュメントの深さを指定します (0 以下の深さの指定は無限大を表す)。メニューの選択肢は、それぞれの可視ページを表示するか、サイトへのリンクを行うために作成されます。フォルダはこの設定によって階層化したメニューに変換されます。
pathsルートフォルダから指定された選択肢への順序付きのパスオプションを含むかどうかを指定する真偽値。この設定は「履歴」もしくは「パンくずリスト」メニューを生成するのに使います。
regexp選択肢の値としてワイルドカードや正規表現が使われるかどうかを指定する真偽属性。ファイルシステムのコマンドラインの正規表現をサポートします。
profileオプションの値を評価する際に使われるプロファイルロケータの名前を指定します。この属性は、オプションと階層化したメニューのためのデフォルトのプロファイルの値も設定します。「*」の指定は、全てのプロファイルロケータの名前を受け入れます。これは、親メニューが選択したプロファイル名を上書きするのに使うことができます。
orderマッチする選択肢の順序を判断するための、カンマで区切られたマッチするパターンの正規表現のリスト、もしくは正規表現のドキュメントパスの値。この属性は、どの選択肢の要素に対してもデフォルトの選択肢の値として適用されます。しかし、複数の選択肢の子供へのマッチを再度順序づけることはありません。もし指定されない場合、複数の選択肢は、含まれるフォルダドキュメントのものとして返される順序に含まれます。この属性にマッチしない選択肢のパスは、順序づけられたものの後に追加されます。
skinメニューのためのレイアウトのヒントを定義する省略可能なデコレータ。この属性は、選択肢や階層化したメニューのデフォルトスキンの値としても使われます。このヒントは、現時点では PALポータルのデコレータでは使われていません。

<menu> 要素は、多数の他のメニュー定義の PSML 要素を含みます。タイトルとメタデータ要素を除いて、これらの要素の相対的な順序は、レイアウトデコレータがそれらを提示する順序を決定します。

要素説明
title?メニュー用のデフォルトのロケール非依存なタイトルを指定する単純な要素。メニューのタイトルは、その長い記述とみなされます。そして、もしメニュー用の短いタイトルが利用可能である場合、デコレータによってはロールオーバー用のテキストとして使う場合があります。もし指定されない場合、メニューの名前が使われます。
short-title?メニュー用のデフォルトのロケール非依存な短いタイトル。短いタイトルは、もし利用可能である場合、デコレータによってはメニューのテキストとして使う場合があります。もし指定されない場合、タイトルのテキストが使われます。
metadata*追加のロケール特有のタイトルと短いタイトルを指定します(省略可)。
options*この順序付きのメニュー要素は、このメニュー定義のためのコンテンツ要素を指定します。
separator*このメニュー定義内で、インラインで含まれるテキスト行を指定するために使われる、順序付きのメニュー要素。
menu*このメニュー定義に含まれる、階層化されたメニューを定義するのに使われる、他の順序付きメニュー要素。
include*このメニュー定義に含める、他のメニューの階層化したメニュー、もしくは選択肢を指定します。含めるメニューの名前はこの順序付きのメニュー要素のテキストです。
exclude*このメニュー定義から除外する、他のメニューの選択肢と階層化したメニューを指定します。除外するための要素に含まれるメニューの名前は、この順序付きのメニュー要素のテキストです。

例:

<menu name="simple">
    <options>/some-top-page.psml,/custom/some-other-page.psml</options>
</menu>
<menu name="top-2-levels" options="/" depth="2" skin="dhtml-pull-down"/>
<menu name="top-role-pages" regexp="true" options="/*" profile="roles"/>
<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>

デフォルトの共通メニュー宣言のための定義は、内部的にポータルサイトコンポーネントによってサポートされます。

<menu name="pages" regexp="true" options="*.psml"/>
<menu name="breadcrumbs" options="~" paths="true"/>
<menu name="navigations">
  <separator>Folders</separator>
  <options regexp="true">./*/</options>
  <include>page-navigations</include>
  <separator>Additional Links</separator>
  <options regexp="true">/*.link</options>
</menu>
<menu name="back" options="../"/>

これらの定義のセパレータのテキストは、内部的に変換されることに注意してください。

メニューの選択肢の定義

<options> 要素は、メニュー内に単一または複数の選択肢を定義します。この単純な要素の文字列は、ページ、もしくはフォルダ、もしくはリンクのメニューの選択肢を作るドキュメントのパスを指定します。複数の選択肢のパスを、パスおよび (もしくは) 正規表現パターンをカンマで区切ったリストとして指定することも可能です。相対パスは、現在のページからの相対パスとして解釈されます。「~」や「@」といった特別なパターンを、現在のページを参照するために使うことができます。この要素は、メニュー要素とたくさんの属性を共有します。

属性説明
depth選択肢のフォルダからのドキュメントの深さを指定します (0 以下の深さは無限大を表します)。メニューの選択肢は、サイトへのそれぞれの可視ページまたはリンクを表示するように作成されます。フォルダは、この設定によって階層化したメニューに変換されます。
pathsルートフォルダから指定された選択肢への順序付きのパスの選択肢を含むかどうかを指定する真偽値。この設定は「履歴」もしくは「パンくずリスト」メニューを生成するのに使います。
regexp選択肢の値としてワイルドカードや正規表現が使われるかどうかを指定する真偽属性。ファイルシステムのコマンドラインの正規表現をサポートします。
profile選択肢の値を評価する際に使われるプロファイルロケータの名前を指定します。この属性は、選択肢と階層化したメニューのためのデフォルトのプロファイルの値も設定します。「*」の指定は、全てのプロファイルロケータの名前を受け入れます。これは、親メニューが選択したプロファイル名を上書きするのに使うことができます。
orderマッチする選択肢の順序を判断するための、カンマで区切られたマッチするパターンの正規表現のリスト、もしくは正規表現のドキュメントパスの値。この属性は、どの選択肢の要素に対してもデフォルトの選択肢の値として適用されます。しかし、複数の選択肢の子供へのマッチを再度順序づけることはありません。もし指定されない場合、複数の選択肢は、含まれるフォルダドキュメントの順番で返される順序に含まれます。この属性にマッチしない選択肢のパスは、順序づけられたものの後に追加されます。
skinメニューの選択肢のレイアウトのヒントを定義するデコレータ(省略可)。このヒントは、現時点では PALポータルのデコレータでは使われていません。

例:

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

メニューのセパレータの定義

<separator> 要素は、メニューに含めるセパレータを定義します。セパレータは、選択肢もしくは階層化したメニューが、メニューの定義内のこの要素以下に現れた場合のみ含まれます。セパレータのテキストは、この要素内のテキスト、もしくはテキストメニュー定義の要素内で指定することが可能です。セパレータ要素に記述可能な属性は 1 つしかありません。

属性説明
skinメニューセパレータのレイアウトのヒントを定義する省略可能なデコレータ。このヒントは、現時点では PALポータルのデコレータでは使われていません。

<separator> 要素は、たくさんの他のメニュー定義の PSML 要素を含みます。

要素説明
title?メニュー用のデフォルトのロケール非依存なタイトルを指定する単純な要素。セパレータのタイトルは、その長い記述とみなされます。そして、もしセパレータのテキストが利用可能である場合、デコレータによってはロールオーバー用のテキストとして使う場合があります。
text?メニュー用のデフォルトのロケール非依存なテキストを指定する単純な要素。セパレータのテキストは必須で、この属性によって指定されようと、セパレータ要素内のテキストとして指定されようと、レイアウトデコレータがメニュー内に挿入するためのテキストとなります。
metadata*ロケール特有の追加のタイトルとセパレータテキスト(省略可)。

例:

<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 PALポータルusers!</title>
    </separator>
    ...
</menu>

メニューをインクルードするための定義

<include> 要素は、選択肢または、他のメニューの階層化した メニューを含みます。含めるメニューの名前は、このエレメントのテキスト値として指定します。この要素に含めることのできる有効な属性は 1 つしかありません。

属性説明
nest指定したメニューが、階層化するためのものかどうかを制御する真偽値。もしこの属性に 'true' が指定された場合、含めるメニューはサブメニューとして階層化されます。そうでないのなら、全ての選択肢と指定したメニューの階層化したメニューは、このメニュー内にインラインで挿入されます。

例:

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

メニューの除外を行うための定義

<exclude> 要素は、選択肢もしくは、他のメニューの階層化した メニューを除外します。このオプションは主に、このメニューから、ポータルページ内の、他のメニューに既に表示されているメニューの選択肢を消去するために使われます。一致する選択肢またはメニューがメニュー定義内のこの要素より上に表示されている場合は、除外されます。除外するメニューの名前は、この単純な要素のテキスト値として指定します。

例:

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

ページレイアウトデコレータ

ページレイアウトデコレータは、ページが PALポータルパイプラインで描画されるとき、ポータルサイトコンポーネントからメニューを要求します。デコレータは、メニューが PSML で定義されることを期待します。カスタムメニューがポータルに表示される前に、デコレータは、カスタムメニューの描画を変更する必要があります。以下に、Velocity レイアウトデコレータの header.vm ファイルから抜き出した例を示します。

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

このコードは、ポータルページ内の標準的なページのタブメニューを描画します。ポータルサイトコンポーネントは Velocity のコンテキスト変数 $site として表れます。空のメニュー定義のための判断は、空のメニューがページコンテンツ内に描画されないことを保証するために設計されています。最後に、デコレータマクロが、メニューコンテンツを展開するために実行されます。一般に、再帰的なマクロの起動で階層化したメニューを描画することをサポートするために、このアプローチを取ります。この場合、デコレータはページオプションだけを期待します。以下に、ページのタブメニューを描画するのに使われるマクロ実装を示します。

#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

このマクロは、ポータルサイトコンポーネントによって提供される、処理されたページメニューの選択肢全てに渡って反復されます。これは、表示されるタブそれぞれを作るための HTML 要素のテーブルデータを描画します。メニュー全体は、単一の行の HTML テーブルとして描画されます。

以下に、ポータルサイトコンポーネントオブジェクトがレイアウトデコーレータに表示する、宣言型のメニューのインタフェースを作るためのプライマリのインタフェースのリストを以下に挙げます。

  • 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>

ポータルサイトコンポーネント

PALポータルのポータルサイトコンポーネントには、 2 つの密接に関係した役割があります。

  1. ユーザからのポータルのリクエスト URL を、サイト内の PSML ページもしくはフォルダ要素にマップします。
  2. サイトでユーザが利用可能なものを反映した、サイトのナビゲーションメニューと、メニューの選択肢を構築します。
一見、これらの機能は、PSML サイト定義を検索し、走査するだけの、比較的シンプルなものであるように見えます。しかし、一度プロファイラーの集約とセキュリティ制約のフィルタリングの複雑さが採り入れられると、マッピングはもはや単純ではなくなります。

メニューの選択肢は、PSML サイトのポータルサイトコンポーネントがマッチさせるビューと一致していることに注意することが重要です。メニュー要素の指定するドキュメントのパスは、PSML フォルダやページを指し示すために使われる物理パスではありません。代わりに、ポータルリクエストを反映するパスは、メニューの選択肢として含める PSML 要素を選択するのに使われます。このように、プロファイリングとセキュリティは、あたかも実行中のリクエスト URL を逆にマップするかのように、メニューの選択肢の集団に自動的に含まれます。