Velocity - Velocity Tools - Layout Servlet

VelocityView

VelocityView Tools

その他のサブプロジェクト

VelocityLayoutServlet (VLS) 概要
	これはベーシックな VelocityViewServlet を拡張したものです。 Velocity Tools をベースとしたプロジェクトにシンプルなレイアウトの制御とカスタマイズ可能なエラー画面を提供します。 Velocity Tools には、このサーブレットを使用するアプリケーション例も含まれています。

インストール

このクラスは VelocityViewServlet (VVS) を拡張したものなので、使うには web.xml の servlet-class の値を以下のクラスへ書き換えるだけです:

org.apache.velocity.tools.view.servlet.VelocityLayoutServlet

設定

VLS を制御する3つの設定を velocity.properties に追加することができます。設定しない場合、以下のデフォルト値が使用されます:

# エラーテンプレートのファイルパス
#  ウェブアプリケーションのルートディレクトリからの相対パス
tools.view.servlet.error.template = Error.vm

# レイアウトテンプレートのディレクトリ
#  ウェブアプリケーションのルートディレクトリからの相対パス
tools.view.servlet.layout.directory = layout/

# デフォルトレイアウトテンプレートのファイルパス
#  レイアウトテンプレートディレクトリからの相対パス
#  ウェブアプリケーションのルートディレクトリからの相対パスではない!
tools.view.servlet.layout.default.template =  Default.vm

レイアウト

レイアウトテンプレートでは必要なのはたった一つ、スクリーンの内容へのリファレンスのみです。最小限のレイアウトテンプレートはこうです:

$screen_content

...でもこれだけだと単なる時間の浪費になるだけです。最低限、このようなことを記述したいと思っていることでしょう:

<html>
<head>
  <title>$!page_title</title>
</head>
<body>
  $screen_content
</body>
</html>

これは基本的な <html>, <head>, <body> タグを全てのスクリーンに書くという手間を省きます。冗長なものを取り除き、作業を軽減する--これがレイアウトのポイントです。レイアウトは内部のスクリーンに、ページのタイトルをコントロールさせているということ注目してください。レイアウトテンプレートはスクリーンを処理した *後に* 同じコンテキストへアクセスし、 VLS によって処理されるからです。スクリーンの中で #set( $page_title = "Hello" ) を行うだけでよいのです。

レイアウトの切り替え

VLS は要求されたページのテンプレートを切り替える 2つの方法を提供します:

1. リクエストパラメータによるレイアウトの指定

リクエストパラメータにクエリ文字列 "layout=MyOtherLayout.vm" が付いているのを VLS が見付けると、デフォルトレイアウトのかわりにそのレイアウトの中にスクリーンを表示します。レイアウトパラメータをクエリデータにどのように入れるかは関係ありません。もし Struts ツールを使用するなら、一般的にはこのようになるでしょう:

これはフォームが POST であっても同様に動作します。

2. リクエストされたスクリーン内でのレイアウトの指定

リクエストされたスクリーンで、このような行を記述:
#set( $layout = "MyOtherLayout.vm" )

これは VLS に "Default.vm" のかわりに "MyOtherLayout.vm" を使うことを指示します。このやり方でレイアウトの設定を行うと、リクエストパラメータによるレイアウトの設定は無視するようになります。

'Navigations', 'Tiles', and How

Turbine や Struts のユーザであれば、もっと高度なレイアウトとスクリーンの設定を望んでいるかもしれません。 "tiles" や "navigations" がお望みですか? Velocity の #parse ディレクティブがあります。簡単ですよ。

まず最初に、このような "tile" を別ファイルとして作成します:

<div id="footer">私がこれを作った!</div>

そして、他のレイアウト用ではないテンプレートと同じように、 webapp のルートディレクトリに配置されている "Footer.vm" というファイルにこのコードがあるとしましょう。


<html>
<head>
  <title>$!page_title</title>
</head>
<body>

$screen_content

#parse('Footer.vm')

</body>
</html>

ね、簡単でしょう?

もし、異なる"footer" ファイルがたくさんあって、スクリーンごとにどれを使うか選びたいときは? 大丈夫! こんなふうに書けばいいのです:


<html>
<head>
  <title>$!page_title</title>
</head>
<body>

$screen_content

#parse( $screen_footer )

</body>
</html>

そしてスクリーンで、 #set( $screen_footer = 'FooFooter.vm' ) と書くだけです。

レイアウトはスクリーン処理後にスクリーンと同じコンテキストを取得し、フッタテンプレートはレイアウトと同じ Velocity コンテキストにアクセスするということを覚えておいてください[訳注: つまり、スクリーン→レイアウト→フッタテンプレートの順に共通のコンテキストが利用されます]。これによって、スクリーンで設定した変数を、レイアウトやフッタで利用することができるのです。

エラー画面

このアイデアは、非常にシンプルなものです。キャッチされない例外、またはエラーがスクリーンやレイアウトの処理中に発生した場合は、 VLS の error() メソッドが呼び出されます。 VLS はハードコードされた html のかわりにテンプレートを表示させるため、 VelocityViewServlet の error() メソッドをオーバライドしています。

このエラースクリーンは他のスクリーンと同様に、レイアウトの中に表示されます。また、エラーのデバッグの手助けとなる以下の値をコンテキストに設定します:

テンプレート内でのキー	値
$error_cause	送出された java.lang.Throwable
$stack_trace	$error_cause.printStackTrace() の出力

MethodInvocationException が error() の呼び出しの原因となっている場合、その元となる例外が取り出されて、上に記述されているように扱われます。しかし、ここではテンプレートのリファレンスの振る舞いが例外の原因の一部なので、 VLSはコンテキストに $invocation_exception として MethodInvocationException 自体も加えます。これにより例外の原因となったリファレンスや、メソッド呼び出しを発見することができます。これらを取得するには、エラーテンプレート内でこのように記述してください:


#if( $invocation_exception )
    おっと! これは MethodInvocationException だ!

    メッセージ: $invocation_exception.message
    リファレンス名: $invocation_exception.referenceName
    メソッド名: $invocation_exception.methodName
#end

[訳注: この文書は木村貴由野瀬直樹が翻訳しました。日本語訳に対するコメントがあれば、report@jajakarta.orgに送って下さい。]