30 second introduction
The template system uses DOM concepts for specifying the dynamic parts, and thus works at a higher level than string-based macro-processors. It works thus not entirely unlike performing DOM modifications using Javascript in a browser. To obtain high performance, the system doesn't provide access to a DOM at runtime, but compiles the template into pcode. It uses a generated java class to access your methods/fields/inner-classes at runtime so the overhead of reflection is minimized and you get the advantage of compile-time checks.
The html concepts which the system provides support for are:
Content substitution: A simple example is to output the real user's name instead of a placeholder in ``<div>You're logged in as John Doe</div>''. Sometimes only parts of the content should be replaced.
Conditional: The ability to omit parts of the template. The parts are defined at compile time, however the inclusion/omitting is determined at runtime. Some web-based shops require customers to login before they can submit orders but allows the customers to collect items in the shopping basket while not logged in. If the customer is not logged in, the ``You're logged in as...'' message <div> element must be omitted, i.e. a conditional.
Tag conditional: Administrative users often have more links available on a page, e.g. to edit information or to display internal company information for an item. For the normal user the links must be omitted and only the plain text should be displayed.
Attribute value: Link destination address (<a href=...>), image source address (<img src=...>), input name/value, etc. are often determined at runtime.
Sub-attribute: Sometimes only a single name in a class attribute should be added (or omitted) and sometimes the style attribute needs to be modified. Changing the complete attribute value makes the template fragile with regard to modifications made by the web designer after the initial development and deployment.
Simple loop: Most web applications make database queries and display the results in a table or list. For each query result, the template system should loop over a designated sample row/list-item and emit the content for each query result, including performing all the replacements etc. inside the sub-template.
Complex loop data: (scoping) Some rows contain complex information, e.g. each row requires separate database queries or complex calculations. Sometimes summary views display several pieces of information which are not combined into a single entity in the rest of the application. It is therefore useful to be able to easily create a local model for each row/list-item in template loops.
Multiple templates in the same servlet: The typical example is the `print friendly' version of a page which cannot be created using only style sheets but must be created using a different template. Usually such pages share almost all dynamic parts and the required template is indicated by e.g. a `print=1' URL argument which makes it difficult to use a specific servlet for each template.
The inverse pattern is to use the same template in several servlets although two completely different implementations for the same page is quite uncommon: I only use this inverted pattern for very simple pages, e.g. `quick and dirty' pages which are not displayed to normal users but only to developers/admins, e.g. debug dumps. The only dynamic parts of those simple pages are the title and a single content substitution in the main body.
Partial template: Parts of AJAX-based pages are updated using Javascript's innerHTML. When the page is designed, the sub-part is designed as an integral part of the complete page rather than a separate template. This creates the need for generating only the sub-part of a template without the overhead of generating the complete page and then chopping off the unwanted (pre and post) parts.