[翻译]VelocityLayoutServlet (VLS) 综观-CSDN博客

这一个基本的VelocityViewServlet的一个扩展。它为基于Velocity Tools 的工程项目提供了一个简单的布局控制和定制的错误显示屏幕。VelocityTools已经推出了一个展示使用这个servlet的示例应用。

安装

由于这个类是VelocityViewServlet（VVS）的一个扩展，因此使用它只要简单的把web.xml条目中servlet-class的值改成：

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

配置设置

为了控制VLS，可以将三个设置加入到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
```
布局

现在，在你的布局模板中，你事实上只需要做的一件事情就是引用屏幕内容（screen content）。因此一个可以被接受的模板可能像这样：

$screen_content

但是这样就让整件事情变成是毫无意义的浪费时间。至少，你大概将要做下面几行所做的事情：
```
<html>
<head>
  <title>$!page_title</title>
</head>
<body>
  $screen_content
</body>
</html>
```
这节省了你在每一个单独的屏幕中（screen）中准备好<html>、<head>和<body>标签。这就是布局的目的：节省精力和消除冗余。请注意这里仍然让内部的屏幕可以控制页面的标题。这样会起作用是因为布局模板是在屏幕准备号以后，通过访问同屏幕一样的上下文环境来实现的，受益于VLS。只要在屏幕中有一个 #set( $page_title = "Hello" )。

多布局

VLS提供两种方法为请求的页面满足一种多布局模板。：

1、在请求参数中指定布局

只要在任何请求参数的查询字符串中加入“layout=MyOtherLayout.vm”，VLS就会找到它（参数指定的布局文件）并且用那个布局，而不是默认的布局来渲染你的屏幕。你如何从查询数据中获取布局参数是没有影响的，只需要它在那里就行了。如果你使用了struts工具，大部分共同的做法可能是这样：

<a href="$link.setRelative('MyScreen.vm').addQueryData('layout','MyOtherLayout.vm')">

但是表单post方式的数据也同样会起作用。

2、为请求的屏幕定制布局。

在请求的屏幕内，放入像下面这样一行：

#set( $layout = "MyOtherLayout.vm" )

这回直接指示VLS使用“MyOtherLayout.vm”而不是“Default.vm”。在这个范围内设置的布局会覆盖有请求参数设置的任何布局。

”导航（Navigations）“，“Tiles”，怎样弄？

你们中间那些Turbine活着Struts用户将可能不仅仅只设置一下布局和屏幕内容。你想要包含任意的“tiles”活着“navigations”，是不是？那么，得益于Velocity内置的#parse指令，这样做事轻而易举的。

首先，把你的“tile”做为一个单独的文件像下面这样创建：
```
<div id="footer">I made this!</div>
```
由于创造能力的缘故，我们假设这段代码在一个像我的应用程序根目录中其他没有被布局的名叫“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' ) 。

记住，你的 #parsed 底部模板将会访问跟你的布局一样的velocity上下文环境，一旦屏幕已经为它准备好了，它就可以获得屏幕的上下文环境了。这样就允许你为布局和底部使用来自你的屏幕所设置的变量。

错误屏幕

OK，这里的概念很简单。如果在你的屏幕和布局处理过程的一些点上抛出了不能被catch的异常或者错误，VLS的error()方法就会被调用。它重写了VelocityViewServlet中默认的error()方法，去渲染一个模板，而不是使用硬编码的html。

这个错误屏幕将会在和其他屏幕一样的规则下，在一个布局中被渲染，而且将会有下面这几个值被放进它里面，以便你调试错误。

变量
值
$error_cause
被抛出的 java.lang.Throwable
$stack_trace
俘获的$error_cause.printStackTrace()输出

#if( $invocation_exception )紧随着error()的调用之后是一个MethodInvocationException 的事件中，根原因被从它的里面被挖掘出来，并且被处理上面描述的那样。但是，由于这里模板的引用行为是部分处于错误中的，VLS同样将把MethodInvocationException作为$invocation_exception添加到它的上下文环境中。这样就允许你去发掘引发了根源错误的引用和方法调用。为了获得这些东西，在你的错误模板中做像下面这样一些事情：

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

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