HTML Templating Module

Introduction

The main goal of the HTML templating framework in eXist-db is a clean separation of concerns. Generating entire pages in XQuery is quick and dirty, but makes maintenance and code sharing difficult. Ideally people should be able to look at the HTML view of an application and modify its look and feel without knowing XQuery. The application logic - written in XQuery - should be kept separate. Likewise, the XQuery developer should only deal with the minimal amount of HTML which is generated dynamically.

The templating module also handles most of the HTTP processing an application requires. It does so using sophisticated features like automatic parameter injection and type conversion. The goal was to remove repeating code like:

In fact you should not see many calls to the HTTP request or session module inside a templating function. It is all handled by parameter injection.

Writing the HTML

The templating module is mainly based on conventions. Wherever possible it tries to make a best guess instead of requiring additional code or annotations to be written. This works as long as the conventions used are sufficiently clear.

The input for the templating framework is always a plain HTML file. The module scans the HTML view for elements with class (or data-template, see below) attributes following a simple convention and tries to translate them into XQuery function calls. By using class attributes, the HTML remains sufficiently clean and does not get messed up with application code. A web designer could take the HTML files and work on them without being bothered by the extra class names.

In the simplest case, a template call inside a class attribute is just the name of a function known in the XQuery context. To start with the usual "Hello world" example:

When the module encounters demo:hello, it will try to find a function named "demo:hello" in all the modules known to the XQuery. If the function's signature follows a certain convention (see below), it will be called and the div will either be replaced or enhanced by whatever the function returns.

Please note that the additional class "grey-box" does not interfere with the template call and is just ignored. "grey-box" might be a class used for styling, so we don't want to remove it. The templating framework will only take a closer look at class names which follow the prefix:local-name pattern.

It is also possible to pass static parameters to a template call. Those are encoded like URI parameters, e.g.: demo:hello?language=de. A static parameter will be passed to the XQuery function as a fallback value if it cannot be determined by looking at the HTTP context (see below).

Templating Functions

A templating function is an ordinary XQuery function in a module which takes at least two parameters (of a certain type), though additional parameters are allowed. If a function does not follow this convention, it will simply be ignored by the templating framework. For example, our "Hello world!" function could be defined as follows:

The two required parameters here are $node and $model. $node contains the HTML node currently being processed: in this case, the div element. $model is an XQuery map with application data. It will be empty for now, but we'll see later why it is important.

Parameter Injection and Type Conversion

The additional parameters, $language and $user, will be injected automatically. The templating framework tries to make a best guess about how to fill those parameters with values. It checks the following 3 contexts for parameters with the same name (in the order below):

1. if the current HTTP request contains a (non-empty) parameter with the same name as the parameter variable, it is used to set the value of the variable

2. if the HTTP session contains an attribute with the same name as the parameter variable, the variable's value will be set to it

3. if the static parameters passed to the template call contain a parameter matching the variable name, it will be used

If neither 1. nor 2. lead to a non-empty value, the function signature will thus be checked for an annotation %templates:default("name", "value1", ..., "valueN"). The first parameter of the annotation should match the name of the parameter variable. All other parameters of the annotation are taken as values for the variable.

If "language" is passed as a parameter in the HTTP request, it will overwrite the static parameter we provided because the HTTP request is checked first.

The templating framework will attempt automatic type conversion for all parameters. If the parameter has a declared type of xs:integer, it will try to cast a parameter it finds into an integer. If the type is node(), the parameter value will be parsed into XML. These conversions may fail and you may get an error if you are passing a parameter with the wrong type.

Additional Annotations

Our "Hello world" example above does not preserve the div from which it was called, but replaces it with a new one which lacks the "grey-box" class. This is the default behavior. To preserve the enclosing div, we should add the XQuery annotation %templates:wrap to the function signature.

A second annotation can be used to provide a default value for a parameter: %templates:default("parameter", "value1", "value2", ...). For example, we may want to set the $language parameter to "en" if the value cannot be determined otherwise:

As you can see, we could remove the wrapping div and just return a string now.

Using the Model to Keep Application Data

In a more complex application, a view will have many templating functions, which all access the same data. For example, take a typical search page: there might be one HTML element to display the number of hits, one to show the query, and another one for printing out the results. All those components need to access the search result. How do you do this in a templating framework?

This is where the $model parameter becomes important. It is passed to all template functions and they can add data to it, which will then be available to nested template calls. A search page could thus contain HTML like this:

The demo:hit-count and demo:result-list occur inside the div calling demo:search. They are thus nested template calls. demo:search would probably perform the actual search operation based on the parameters passed by the user. But instead of directly printing the search result in HTML, it delegates this to the nested templates. demo:search might be implemented as:

demo:search differs from the functions we have seen so far in that it returns an XQuery map and not HTML or an atomic type. If a templating function returns a map, the templating framework will proceed as follows:

1. add the returned map to the current $model map (adding it to the map entries produced by any ancestor templates calling it)

2. resume processing the children of the current HTML node

The demo:hit-count and demo:result-list can thus access the query results in the $model map passed to them:

Set-Up

The templating module is entirely implemented in XQuery. It provides a single public function, templates:apply. A complete main module which calls the templating framework to process an HTML file passed in the HTTP request body could look as follows:

This module would be called from the URL rewriting controller. For example, we could add a rule to controller.xql to pass any .html resource to the above main query (saved to modules/view.xql):

The only part of the main module code which might look a bit unusual is the inline lookup function: the templating module uses dynamic function calls to execute template functions in application modules. But unfortunately, XQuery modules can only "see" functions in their own context. There is thus no way for the templating module to determine what functions are defined in application modules which are outside its context. We thus need to "help" it by providing a callback function to resolve function references. The lookup function is defined in the main context and can thus access all the modules imported into the main module.

Normally you can just copy and paste the main module code as given above. To adopt it to your own application, just import your application modules and you're done.

Integration with eXide

The "New Application" templates in eXide already include the HTML templating module and configure the URL rewriting to call it for any path ending in .html. Using eXide is thus the easiest way to get started with the templating framework. Please consult the Getting Started with Web Application Development guide to read more.

Where to Find the Module?

If you generate your application with eXide, a copy of the HTML templating module will be included, so you can customize it. If you rather want to make sure you have the latest version of the templating module: the shared-resources application also exports the module. This will always be the latest version. You could thus define a dependency on the shared-resources app (see the packaging documentation). In this case you can just import the module by its namespace URI, but without specifying a location.

The documentation and demo applications all read the templating module from shared-resources.

Pre-defined Template Commands

The templating module defines a number of general-purpose templating functions, which are described below for reference. templates:surround is probably the most powerful one and used by almost all HTML views.