Review Template configuration properties for web-specific keys

[bclozel]

In #15131, the team decided to review and possibly move the configuration keys in FreeMarkerProperties, GroovyTemplateProperties and MustacheProperties that are related to web-only use cases.

Doing so should:

• clear up exactly when those configuration keys are applied
• avoid confusion around web and non-web uses cases and what is being configured
• allow to apply sane web defaults for those configuration keys

[mbhave]

See also #11199 which might affect how we structure these properties.

[bclozel]

Spring Boot configuration support for templating engines

Spring Boot offers templating configuration for Mustache, Thymeleaf, Freemarker and Groovy Templates. Templating engines can be used in various situations:

• in web apps for rendering HTML pages
• in web apps for rendering "textual" files like txt, css or escaped files like JavaScript
• in apps that aren't doing web for text files, XML files, emails, etc

When looking at the configuration properties, one can find the basic configuration for setting
up a templating engine (location, caching, etc):

spring.engine.prefix=
spring.engine.suffix=
spring.engine.cache=
spring.engine.enabled=
spring.engine.charset=
spring.engine.(resource|template)-loader-path=

Other configuration keys are specific to web infrastructure:

spring.engine.allow-request-override=
spring.engine.allow-session-override=
spring.engine.content-type= 
spring.engine.expose-request-attributes=
spring.engine.expose-session-attributes=

In some cases we've even dealt with web stacks in different namespaces:

spring.engine.servlet.key=
spring.engine.reactive.other-key=

Some configuration keys look generic enough, but they can actually configure how the resolved
templates should be rendered (as an HTML file, escaping enabled or not, etc).
Ultimately, the template file extensions (the suffix configuration part) takes precedence
for most templating engines:

spring.engine.(mode|settings.*)=
spring.engine.suffix= 

Using a templating engine in Spring Boot

The most common case seems to be about using a templating engine to render HTML pages
in a web application. This is also the most straightforward configuration for developers.

Non-web applications are also supported. Depending on the use case and the choice of
templating engine, developers might have to change large parts of the configuration defaults
(templating mode and/or template files extensions, escaping options, etc).

If an application needs to have both web and non-web templates, the required configuration
really depends on the templating library.

JMustache

By default Spring Boot builds a Mustache compiler that escapes HTML characters.
The non-web parts should not use any of Spring Boot's infrastructure and set up
a dedicated Mustache.Compiler instance with HTML escaping disabled.

Thymeleaf

Spring Boot will auto-configure a SpringTemplateEngine and/or a SpringWebFluxTemplateEngine,
which can be injected in a component and used to render templates directly.

Note that the Thymeleaf view resolver can resolve view names like "example" and will use the
configured prefix, resolving "example.html", but it also allows to resolve "script.js" if
used as an explicit name.

Last, developers can contribute custom ITemplateResolver components, which are ordered.

Freemarker

The Spring Boot auto-configuration contributes a freemarker.template.Configuration which
only applies the basic options (template loader path, settings, encoding). The prefix/suffix
options are only used for the web bits.

So this freemarker.template.Configuration can be used to render non-web templates in
components.

Summary

The templating engine support in Spring Boot is really web-centric.
Spring Boot often configures the bare minimum for non-web cases (a Freemarker Configuration,
a Thymeleaf SpringTemplateEngine, a Mustache Compiler) and developers might reuse or
duplicate infrastructure for their own needs.

There is little benefit in separating web and non-web settings; it would make things complicated
and would differ from one engine to the other. It's hard to draw a line between what is web specific and what's not: some configuration keys are really web specific, but default values on other keys point to a web-only use case. Also, servlet vs. reactive support adds another dimension to that.

Tuning the templating engine for the web case should be our top priority, as long as we re-expose
as components all infrastructure bits that could be reused in non-web use cases when we can.