Main class for the execution of templates.
In order to execute Thymeleaf templates, an instance of this class (or one of its subclasses) must be created.
Creating an instance of TemplateEngine
An instance of this class can be created at any time by calling its constructor:
final TemplateEngine templateEngine = new TemplateEngine(); Creation and configuration of TemplateEngine instances is expensive, so it is recommended to create only one instance of this class (or at least one instance per dialect/configuration) and use it to process multiple templates.
Configuring the TemplateEngine
Once created, an instance of TemplateEngine has to be configured by setting the following required parameters:
- One or more Template Resolvers (instances of {@link ITemplateResolver}), in charge of reading or obtaining the templates so that the engine is able to process them. If only one template resolver is set (the most common case), the {@link #setTemplateResolver(ITemplateResolver)}method can be used for this. If more resolvers are to be set, both the {@link #setTemplateResolvers(Set)} and {@link #addTemplateResolver(ITemplateResolver)} methodscan be used.
Also, the following parameters can be optionally set:
- One or more Dialects (instances of {@link IDialect}), defining the way in which templates will be processed: DOM processors, expression parsers, etc. If no dialect is explicitly set, a unique instance of {@link org.thymeleaf.standard.StandardDialect}(the Standard Dialect) will be used.
- Dialects define a default prefix, which will be used for them if not otherwise specified.
- When setting/adding dialects, a non-default prefix can be specified for each of them.
- Several dialects can use the same prefix, effectively acting as an aggregate dialect.
- All specified dialects will be validated to ensure no conflicts with DOCTYPE translations or resolution entries exist. Dialects defining a DOCTYPE translation or resolution entry equal to another one in a different dialect are not considered to be in conflict.
- Dialect leniency will be computed per-prefix, so that a prefix will be considered to be lenient if at least one of the dialects configured for it is lenient.
- Note that defining a non-default prefix for a dialect might affect its validation features if this dialect includes DTD files for such purpose (e.g. the Standard Dialect).
- One or more Message Resolvers (instances of {@link IMessageResolver}), in charge of resolving externalized messages. If no message resolver is explicitly set, the default setting specified by {@link #setDefaultMessageResolvers(Set)} will be applied (thisdefault setting defaults itself to a single instance of {@link StandardMessageResolver}). If only one message resolver is set, the {@link #setMessageResolver(IMessageResolver)} methodcan be used for this. If more resolvers are to be set, both the {@link #setMessageResolvers(Set)} and {@link #addMessageResolver(IMessageResolver)} methodscan be used.
- A set of Template Mode Handlers (instances of {@link ITemplateModeHandler}, which will take care of reading/parsing templates and also writing the results of processing them for a specific template mode. The presence of these template mode handlers defines which are the valid values for the templateMode attribute of template resolution results ( {@link TemplateResolution#getTemplateMode()}). If not explicitly set, template mode handlers will be initialized to {@link StandardTemplateModeHandlers#ALL_TEMPLATE_MODE_HANDLERS}.
- A Cache Manager (instance of {@link ICacheManager}. The Cache Manager is in charge of providing the cache objects (instances of {@link org.thymeleaf.cache.ICache}) to be used for caching (at least) templates, fragments, messages and expressions. By default, a {@link StandardCacheManager} instance is used. If a null cache manager is specified by calling{@link #setCacheManager(ICacheManager)}, no caches will be used throughout the system at all.
Template Execution
1. Creating a context
All template executions require a context. A context is an object that implements the {@link IContext} interface, and that contains at least the followingdata:
- The locale to be used for message externalization (internationalization).
- The context variables. A map of variables that will be available for use from expressions in the executed template.
Two {@link IContext} implementations are provided out-of-the-box:
- {@link org.thymeleaf.context.Context}, a standard implementation containing only the required data.
- {@link org.thymeleaf.context.WebContext}, a web-specific implementation extending the {@link org.thymeleaf.context.IWebContext} subinterface, offeringrequest, session and servletcontext (application) attributes in special variables inside the context variables map. Using an implementation of {@link org.thymeleaf.context.IWebContext} is required when using Thymeleaf for generating HTML/XHTML interfaces in web applications.
Creating a {@link org.thymeleaf.context.Context} instance is very simple:
final IContext ctx = new Context();
ctx.setVariable("allItems", items); A {@link org.thymeleaf.context.WebContext} would also need {@link javax.servlet.http.HttpServletRequest} and {@link javax.servlet.ServletContext} objects as constructor arguments:
final IContext ctx = new WebContext(request, servletContext);
ctx.setVariable("allItems", items); See the documentation for these specific implementations for more details.
2. Template Processing
In order to execute templates, the {@link #process(String,IContext)} and{@link #process(String,IContext,Writer)} methods can be used:
Without a writer, the processing result will be returned as a String:
final String result = templateEngine.process("mytemplate", ctx); By specifying a writer, we can avoid the creation of a String containing the whole processing result by writing this result into the output stream as soon as it is produced from the processed DOM. This is specially useful in web scenarios:
templateEngine.process("mytemplate", ctx, httpServletResponse.getWriter()); The "mytemplate" String argument is the template name, and it will relate to the physical/logical location of the template itself in a way configured at the template resolver/s.
@author Daniel Fernández
@since 1.0