Velocity - Velocity Tools - Layout Servlet

VelocityView

VelocityView Tools

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

This is an extension to the basic VelocityViewServlet. It provides a simple layout control and customizable error screens for Velocity Tools based projects. Velocity Tools is distributed with an example app demonstrating the use of this servlet.

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

インストール

Since this class is an extension of the VelocityViewServlet (VVS), to use it simply change the servlet-class value of the web.xml entry to the following class:

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

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

設定

Three settings can be added to velocity.properties to control the VLS, or the following default values will be used:

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

# Filepath for error template, 
#  relative to web application root directory
tools.view.servlet.error.template = Error.vm

# Directory for layout templates, 
#  relative to web application root directory
tools.view.servlet.layout.directory = layout/

# Filepath of the default layout template 
#  relative to the layout directory 
#  NOT relative to the root directory of the webapp!
tools.view.servlet.layout.default.template =  Default.vm

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

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

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

レイアウト

Now, in your layout templates, the only thing you really need is the screen content reference. So an acceptable layout template could be:

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

$screen_content

...but that would make this whole thing an idiotic waste of time. At the least, you'll probably want to do something along these lines:

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

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

This saves you the trouble of doing the basic <html>,<head>, and <body> tags in every single screen. That's the point of layouts: to save effort and eliminate redundancy. Note that this still lets the inner screen control the title of the page. This works because the layout template is blessed by the VLS with access to the same context as the screen *after* the screen is done with it. Just do a #set( $page_title = "Hello" ) in the screen.

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

レイアウトの切り替え

VLS provides two ways to specify an alternate template for a requested page:

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

1. Specify the layout in the request parameters

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

Just add the query string "layout=MyOtherLayout.vm" to any request params and the VLS will find it and render your screen within that layout instead of the default layout. It don't matter how you get the layout param into the query data, only that it's there. If you're using the struts tools, the most common will likely be:

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

but form post data will work just as well.

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

2. Specify the layout in the requested screen.

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

In the requested screen, put a line like this:
#set( $layout = "MyOtherLayout.vm" )

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

This will direct the VLS to use "MyOtherLayout.vm" instead of "Default.vm". Setting the layout in this fashion will override any layout set by the request parameters.

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

'Navigations', 'Tiles', and How

Those of you who are (or were) Turbine or Struts users will probably want to do more than just set the layout and screen content. You want to include arbitrary "tiles" or "navigations", right? Well, thanks to Velocity's built-in #parse directive, this is easy.

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

First, create your "tile" as a separate template file like:

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

<div id="footer">I made this!</div>

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

For creativity's sake, we'll pretend this code is in a file named "Footer.vm" that is located in the root of my webapp like my other non-layout templates.

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


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

$screen_content

#parse('Footer.vm')

</body>
</html>

Easy, eh?

ね、簡単でしょう?

Now, what if you have a lot of different "footer" files and you want your screen to decide which one will be used? No problem! Do something like this:

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


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

$screen_content

#parse( $screen_footer )

</body>
</html>

and in your screen, just do #set( $screen_footer = 'FooFooter.vm' ).

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

Remember, your #parsed footer template will have access to the same velocity context as your layout, which gets the screen's context once the screen is done with it. This lets you set variables for the layout and footer to use from your screens.

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

エラー画面

Ok, the idea here is pretty simple. If an uncaught exception or error is thrown at some point during the processing of your screen and layout, the error() method of the VLS is called. This overrides the default error() method of the VelocityViewServlet to render a template instead of hardcoded html.

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

This error screen will be rendered within a layout under the same rules as any other screen, and will have the following values placed in its context to help you debug the error:

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

Key available to Template	Value
$error_cause	java.lang.Throwable that was thrown
$stack_trace	captured output of $error_cause.printStackTrace()

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

In the event that a MethodInvocationException is behind the calling of error(), the root cause is extracted from it and dealt with as described above. But, since template reference behavior is partly at fault here, the VLS will also add the MethodInvocationException itself to the context as $invocation_exception. This allows you to discover the reference and method call that triggered the root cause. To get those, do something like this in your error template:

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


#if( $invocation_exception )
    oh joy! it's a MethodInvocationException!

    Message: $invocation_exception.message
    Reference name: $invocation_exception.referenceName
    Method name: $invocation_exception.methodName
#end


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

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

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