Thymeleaf

Overview

Thymeleaf is an HTML-friendly template engine that is an alternative to the IdP’s current “primary” view technology, Velocity. Thyemleaf has a number of potential advantages over Velocity, including support for “natural templates”, that is the ability to render a template in a browser for testing and design purposes (typically involving separate design teams who specialize in that sort of work) while using the same template at runtime.

It is somewhat less friendly to embedding extensive “logic” in its templates than Velocity, and is definitely a fair bit more complex to use, but has a lot of advantages for those who know it or are willing to learn it.

Partly for these reasons, and also as a potential hedge against a lack of active maintainers for Velocity, we have made this plugin available as an adoption vehicle for a subset of the community that has requested support for Thymeleaf. In this phase of the project, we have (in V5.1) enhanced the configuration of the IdP internally to support extension of the view technology set at runtime via plugins, and added additional properties to allow finer-grained control of which view resolvers are used and in what order.

At present, it is not practical to fully disable Velocity, but a future IdP version may evolve in that direction.

Plugin Installation

For a detailed guide on how to install plugins, see here.

In summary, use the plugin command that ships with the IdP to install the plugin by pluginId.

Installation

C:>\opt\shibboleth-idp\bin\plugin.bat -I net.shibboleth.idp.plugin.thymeleaf

or

$ /opt/shibboleth-idp/bin/plugin.sh -I net.shibboleth.idp.plugin.thymeleaf

Configuration

Installing this plugin has the effect of adding in the necessary libraries to use Thymeleaf with views, and configures support for this “ahead” of Velocity such that any view template ending in an “.html” file extension in the usual locations (or additional ones you configure via idp.views) will be selected ahead of existing Velocity templates (which have a “.vm” file extension).

Installing the plugin will not disable or replace Velocity, nor does it prevent the use of existing templates. In fact, under most conditions, installing this plugin will not result in any obvious changes because no correspondiing templates exist. It does introduce the small overhead of checking for matching templates whenever a view is rendered.

As Velocity does, Thymeleaf has the basic notion of a “context” containing various defined objects, and for the moment, the same objects defined for the Velocity views are available with Thymeleaf, along with its own built-in objects and behavior.

While there is nothing generally needed to configure this plugin, there are a couple of new properties defined for controlling it while installed:

• idp.views.thymeleaf.order

  • This is an integer controlling the relative order of the various view resolvers in the IdP as they search for templates. By default, this is set to “5”, which is less than the default value applied to Velocity, which is 10. The JSP/internal resolver is set to 20, so you can set the property to, for example, 15, to place it after Velocity in order.

• idp.views.thymeleaf.activationCondition

  • Thus can be set to the Spring Bean ID of a Predicate<String> that will be tested to determine whether the view resolver should run or be skipped. The parameter is the base name of the view being rendered. For example, setting this to “shibboleth.Conditions.FALSE” will simply disable the resolver while the plugin remains installed, if desired for some reason. A custom condition could be scripted to allow the resolver to activate only for specific views or based on other criteria.