レイアウトデコレータについて

レイアウトデコレータは、ポータルページのデザインを構成するファイル群です。 レイアウトデコレータは、1 つの PSML ファイルを表現するポータルページのヘッダーとフッターを記述するテンプレートで処理されます。 テンプレート言語には Velocity を用います。 PALポータルはテンプレート部分を汎用的に実装されているので、テンプレート言語に JSP も利用可能ですが、Velocity を標準でサポートします。

構成ファイル

レイアウトデコレータは、webapps/palportal/decorations/layout に配置されます。 このディレクトリをルートディレクトリとして、レイアウトデコレータの名前でディレクトリを作成して、以下のファイルを配置します。

  • decorator.properties
  • header.vm
  • footer.vm
  • css/styles.css
たとえば、mydesign というレイアウトデコレータを利用したい場合は、webapps/palportal/decorations/layout/mydesign ディレクトリを作成して、上記のファイルを配置します。

基本設定(decorator.properties)

decorator.properties ファイルは、レイアウトデコレータの基本情報を保持します。 実際のところ、このファイルは空でも構いませんが、他の API が使用可能なデコレータを探すために使用されるので、ファイルは存在する必要があります。 ですので、下記の定義にあるプロパティは 全てオプションであると仮定しても問題ありません。

プロパティ名説明デフォルト
base.css.class この値は、ヘッダーのテンプレートファイルの一番上の要素タグの中に配置されます。 デコレータ名
stylesheetデコレータのスタイルシートへの相対パスcss/styles.css
headerデコレーションのヘッダーテンプレートへの相対パスheader.vm
footerデコレーションのフッターテンプレートへの相対パスfooter.vm

テンプレートファイル

テンプレートファイルは、ヘッダーテンプレートとフッターテンプレート二より構成されます。

ヘッダーテンプレート

ヘッダーテンプレートファイル header.vm は、ポータルページのヘッダー部分を生成します。

注意: 前提事項として、HTML と CSS についての十分な知識があると仮定してあります。 デコレータを作成するにあたり、基本的な Velocity の知識はあれば良いですが、必須の知識ではありません。

通常、header.vm では、上部に下記のようにレイアウトデコレータで利用するパラメータの設定等を行います。

        
#set($portalMode = "standard")##
## Add the current layouts configuration values to the context
#defineLayoutObjects()##
## Loads our custom macros
#parse($layoutDecoration.getResource("decorator-macros.vm"))##
## Username
#set($username = $JS2RequestContext.request.remoteUser)##
## Check edit
#set($_actions = $layoutDecoration.actions)##
#foreach ($_action in $_actions)##
  #if($_action.actionName == "edit")##
    #set ($editable = true)##
  #end##
#end##
#set($layoutId = $jetspeed.currentFragment.id)##
#set($servletName = $JS2RequestContext.request.servletPath)##
#initMessageResourceBundles()##

#defineLayoutObjects()は、Velocity でマクロと言われるものです。 マクロは、事前に定義された Velocity の小さなコードで、Velocity テンプレートの中で再利用されます。 これから使用する全てのグローバルマクロ (このマクロも含む) は、webapps/palportal/WEB-INF/jetspeed_macros.vm で定義されています。 もし、カスタムマクロを作成したい場合は、レイアウトデコレータ内に decorator-macros.vm を作成して、その中にカスタムマクロを記述します。

#defineLayoutObjects()は、様々な値をレイアウトデコレータ内で利用可能にします。 設定された値は、header.vm や footer.vm などの様々なテンプレートからアクセス可能になります。 #defineLayoutObjects() では、webapps/palportal/WEB-INF/jetspeed_macros.vm で以下のように記述されています。

        
#macro (defineLayoutObjects)
  #set($preferedLocale = $JS2RequestContext.locale)
  #set($rootFragment = $jetspeed.currentFragment)
  #set($site = $request.getAttribute("org.apache.jetspeed.portalsite.PortalSiteRequestContext"))
  #set($theme = $request.getAttribute("org.apache.jetspeed.theme"))
  #set($layoutDecoration = $theme.getDecoration($rootFragment))
#end

#set() は、Velocity の変数に値を設定する関数です。 これは Velocityで指示子と呼ばれるものです。 指示子はオリジナルの関数であり、マクロではありません。 #set()は、イコール記号の右辺にある値を受け取り左辺へ割り当てます。 Velocity の変数は $ で始まる文字列になります。

全てのVelocityテンプレートで利用可能なオブジェクトは、$someObjectという書き方で参照することができます。 メソッドの実行は、$someObject.getFoo() の様に書くことで実行できます。 getFoo()を実行する場合、引数を取らないgetterメソッドは、$someObject.fooという記述も可能です。 この $JS2RequestContext に関しては、org.apache.jetspeed.RequestContext のインスタンスで Velocity で使用できるように、PALポータルによってインスタンス化されています。 org.apache.jetspeed.RequestContext の JavaDoc を見るとわかりますが、$JS2RequestContext.locale は、現在のポートレットのユーザーのロケールとなる、java.util.Locale のインスタンスを渡しています。

次に、#set($rootFragment = $jetspeed.currentFragment) という set の行は、$rootFragment と呼ばれるインスタンスを生成しています。 これは、org.apache.jetspeed.om.page.ContentFragment のインスタンスで、ページ内のルートフラグメントです。 通常ルートフラグメントはレイアウトポートレットになります。

$request は、javax.servlet.http.HttpServletRequestのインスタンスで、PALポータルから Velocity に渡されたオブジェクトを取り出します。$site$theme は、それぞれ org.apache.jetspeed.portalsite.PortalSiteRequestContextorg.apache.jetspeed.decoration.Theme です。

パラメータの設定後、header.vm では、<html> から始まるタグを記述していきます。

  
<html>
  <head>
    #includeHeaderResource()
    <base href="#BaseHref()">
    <meta http-equiv="Content-type" content="#ContentType()" />
    <meta http-equiv="Content-style-type" content="text/css" />
    #IncludeStylesheets()
    <title>#PageTitle()</title>
    <meta name="version" content="#SiteVersionTag()">
    <meta name="keywords" content="#PageKeywords()" />
    <meta name="description" content="#PageDescription()" />
    <script type="text/javascript" src="#GetPageResource('js/jquery-1.2.6.min.js')"></script>
    <script type="text/javascript" src="#GetPageResource('js/ui-1.5.2/ui.core.packed.js')"></script>
    <script type="text/javascript" src="#GetPageResource('js/ui-1.5.2/ui.sortable.packed.js')"></script>
    <script type="text/javascript" src="#GetPageResource('js/main.js')"></script>
  </head>
<body class="#PageBaseCSSClass()">
  <input type="hidden" id="ajaxUrl" value="#BaseHref()ajaxapi$JS2RequestContext.request.pathInfo"/>
  <div class="#PageBaseCSSClass()">
...
<html>

最初に、 <base href="#BaseHref()"> は、ウェブのリソースの場所の解決をするためのベースを定義する際に使用します。 <base> の議論については、W3C Schools Referenceを参照してください。 もしすでにあなたが PALポータルで遊んだ経験があるのであれば、一貫した html やスタイルシートへのパスを取得するのを妨げる、幾通りもの非常にややこしい URL リライトの問題に気づくでしょう。 BASEタグを定義することにより、一貫した html やスタイルシートへのパスを取得するのを妨げる、URL リライトの問題が解決されます。

#BaseHref() マクロは、単にウェブアプリケーションのルートディレクトリへの絶対パスを作成します。 このコードは、サーブレットAPIを使って記述した場合、以下の通りです。

  
HttpServletRequest request;
StingBuffer baseHref = new StringBuffer(request.getScheme())
     .append("://").append(request.getServerName())
	 .append(":").append(request.getServerPort())
	 .append(request.getContextPath()).append("/");
return baseHref.toString();		 

Velocity マクロのコードは簡潔になり、以下の通りです。

  
${request.scheme}://${request.serverName}:${request.serverPort}${request.contextPath}

#ContentType() は text/htmlと、UTF-8 のような適切なエンコードの種類を返します。

#PageBaseCSSClass() は base.css.class プロパティの値が利用され、スタイルシートの適用範囲を指定するために body タグ直下のタグでスタイルクラスとして適用するためなどに用いられます。

フッターテンプレート

footer.vm についても header.vm と同様に記述することができます。

スタイルシート

通常のCSSと同様に記述することができます。

レイアウトデコレータの追加

新規にレイアウトデコレータを追加したい場合は、上記のファイル群を作成し、webapps/palportal/decorations/layout/<mydesign> 以下に配置することで <mydesign> が有効になります。デコレータの追加には、ポータルの再起動は必要ありません。

追加したレイアウトデコレータはサイトエディターから選択することができます。 設定方法の詳細については「管理ガイド」を参照してください。