This is another layout sevlet that will preserve the direct streaming of the page towards the response stream without caching it into memory, built on the basis of Nathan's VelocityLayoutServlet.
The following directives are used to control the behaviour of the page:
- #layout("layout-template") - The layout of this page. If not specified, the page will use the default layout (see below).
- #head("text") - Put text in the page header. Cumulative if used several times.
- #title("title") - the title of the page.
- #page-parameter("parameter-name","parameter-value"") - a named parameter.
The layout page can then use equivalent properties on the $page object: $page.layout, $page.title, $page.head, every defined $page.parameter-name, and the page template path in $page.template.
It is the responsability of the layout template writer to use these references as adequate, as in:
<html>
<head>
<title>$!page.title</title>
$!page.head
</head>
<body>
... #parse($page.template) ...
Please note that the arguments you pass to those directives can contain VTL, but will be evaluated before the page is reached, when the request is received. It means you cannot use values that are dynamically calculated by previous statements in the page.
Let's say you want to have the title reflect some HTTP query parameters, you can do something like: #title("Viewing: $query.document") from within the page. What you cannot do is something like: #set($title="Viewing: $query.document") & #title($title).
The following properties of velocity.properties control the behaviour of the layout servlet:
- tools.view.servlet.layout.directory the directory in which all layouts will be found. Default is /layout.
- tools.view.servlet.layout.default.template the default layout template. Default is default.vtl.
- tools.view.servlet.error.template the error template. Default is error.vtl.
When the resource loader cache is off, the page template is parsed twice per request. Apart from a performence issue, there is also a problem with the #head directive since it works in a cumulative way. Since there is no generic way for the servlet to know whether cache is on or off, there is currently no simple workaround to this problem, which means that cache MUST be turned on for #head() to work properly.
The patch is attached. Please note that the new directives make use of the new velocity-1.5 TemplateInitException, so you will have to compile velocity-tools against velocity-1.5-dev. Otherwise you can easily adapt the sources to have it work with velocity-1.4 by replacing TemplateInitException with a generic Exception.