[[webflux-view]] = View Technologies [.small]#xref:web/webmvc-view.adoc[See equivalent in the Servlet stack]# The rendering of views in Spring WebFlux is pluggable. Whether you decide to use Thymeleaf, FreeMarker, or some other view technology is primarily a matter of a configuration change. This chapter covers the view technologies integrated with Spring WebFlux. For more context on view rendering, please see xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution[View Resolution]. WARNING: The views of a Spring WebFlux application live within internal trust boundaries of the application. Views have access to beans in the application context, and as such, we do not recommend use the Spring WebFlux template support in applications where the templates are editable by external sources, since this can have security implications. [[webflux-view-thymeleaf]] == Thymeleaf [.small]#xref:web/webmvc-view/mvc-thymeleaf.adoc[See equivalent in the Servlet stack]# Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML templates that can be previewed in a browser by double-clicking, which is very helpful for independent work on UI templates (for example, by a designer) without the need for a running server. Thymeleaf offers an extensive set of features, and it is actively developed and maintained. For a more complete introduction, see the https://www.thymeleaf.org/[Thymeleaf] project home page. The Thymeleaf integration with Spring WebFlux is managed by the Thymeleaf project. The configuration involves a few bean declarations, such as `SpringResourceTemplateResolver`, `SpringWebFluxTemplateEngine`, and `ThymeleafReactiveViewResolver`. For more details, see https://www.thymeleaf.org/documentation.html[Thymeleaf+Spring] and the WebFlux integration https://web.archive.org/web/20210623051330/http%3A//forum.thymeleaf.org/Thymeleaf-3-0-8-JUST-PUBLISHED-td4030687.html[announcement]. [[webflux-view-freemarker]] == FreeMarker [.small]#xref:web/webmvc-view/mvc-freemarker.adoc[See equivalent in the Servlet stack]# https://freemarker.apache.org/[Apache FreeMarker] is a template engine for generating any kind of text output from HTML to email and others. The Spring Framework has built-in integration for using Spring WebFlux with FreeMarker templates. [[webflux-view-freemarker-contextconfig]] === View Configuration [.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-freemarker-contextconfig[See equivalent in the Servlet stack]# The following example shows how to configure FreeMarker as a view technology: [tabs] ====== Java:: + [source,java,indent=0,subs="verbatim,quotes"] ---- @Configuration @EnableWebFlux public class WebConfig implements WebFluxConfigurer { @Override public void configureViewResolvers(ViewResolverRegistry registry) { registry.freeMarker(); } // Configure FreeMarker... @Bean public FreeMarkerConfigurer freeMarkerConfigurer() { FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); configurer.setTemplateLoaderPath("classpath:/templates/freemarker"); return configurer; } } ---- Kotlin:: + [source,kotlin,indent=0,subs="verbatim,quotes"] ---- @Configuration @EnableWebFlux class WebConfig : WebFluxConfigurer { override fun configureViewResolvers(registry: ViewResolverRegistry) { registry.freeMarker() } // Configure FreeMarker... @Bean fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply { setTemplateLoaderPath("classpath:/templates/freemarker") } } ---- ====== Your templates need to be stored in the directory specified by the `FreeMarkerConfigurer`, shown in the preceding example. Given the preceding configuration, if your controller returns the view name, `welcome`, the resolver looks for the `classpath:/templates/freemarker/welcome.ftl` template. [[webflux-views-freemarker]] === FreeMarker Configuration [.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-freemarker[See equivalent in the Servlet stack]# You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker `Configuration` object (which is managed by Spring) by setting the appropriate bean properties on the `FreeMarkerConfigurer` bean. The `freemarkerSettings` property requires a `java.util.Properties` object, and the `freemarkerVariables` property requires a `java.util.Map`. The following example shows how to use a `FreeMarkerConfigurer`: [tabs] ====== Java:: + [source,java,indent=0,subs="verbatim,quotes"] ---- @Configuration @EnableWebFlux public class WebConfig implements WebFluxConfigurer { // ... @Bean public FreeMarkerConfigurer freeMarkerConfigurer() { Map variables = new HashMap<>(); variables.put("xml_escape", new XmlEscape()); FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); configurer.setTemplateLoaderPath("classpath:/templates"); configurer.setFreemarkerVariables(variables); return configurer; } } ---- Kotlin:: + [source,kotlin,indent=0,subs="verbatim,quotes"] ---- @Configuration @EnableWebFlux class WebConfig : WebFluxConfigurer { // ... @Bean fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply { setTemplateLoaderPath("classpath:/templates") setFreemarkerVariables(mapOf("xml_escape" to XmlEscape())) } } ---- ====== See the FreeMarker documentation for details of settings and variables as they apply to the `Configuration` object. [[webflux-view-freemarker-forms]] === Form Handling [.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-freemarker-forms[See equivalent in the Servlet stack]# Spring provides a tag library for use in JSPs that contains, among others, a `` element. This element primarily lets forms display values from form-backing objects and show the results of failed validations from a `Validator` in the web or business tier. Spring also has support for the same functionality in FreeMarker, with additional convenience macros for generating form input elements themselves. [[webflux-view-bind-macros]] ==== The Bind Macros [.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-bind-macros[See equivalent in the Servlet stack]# A standard set of macros are maintained within the `spring-webflux.jar` file for FreeMarker, so they are always available to a suitably configured application. Some of the macros defined in the Spring templating libraries are considered internal (private), but no such scoping exists in the macro definitions, making all macros visible to calling code and user templates. The following sections concentrate only on the macros you need to directly call from within your templates. If you wish to view the macro code directly, the file is called `spring.ftl` and is in the `org.springframework.web.reactive.result.view.freemarker` package. For additional details on binding support, see xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-simple-binding[Simple Binding] for Spring MVC. [[webflux-views-form-macros]] ==== Form Macros For details on Spring's form macro support for FreeMarker templates, consult the following sections of the Spring MVC documentation. * xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros[Input Macros] * xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros-input[Input Fields] * xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros-select[Selection Fields] * xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros-html-escaping[HTML Escaping] [[webflux-view-script]] == Script Views [.small]#xref:web/webmvc-view/mvc-script.adoc[See equivalent in the Servlet stack]# The Spring Framework has a built-in integration for using Spring WebFlux with any templating library that can run on top of the {JSR}223[JSR-223] Java scripting engine. The following table shows the templating libraries that we have tested on different script engines: [%header] |=== |Scripting Library |Scripting Engine |https://docs.ruby-lang.org/en/master/ERB.html[ERB] |https://www.jruby.org[JRuby] |https://docs.python.org/2/library/string.html#template-strings[String templates] |https://www.jython.org/[Jython] |=== TIP: The basic rule for integrating any other script engine is that it must implement the `ScriptEngine` and `Invocable` interfaces. [[webflux-view-script-dependencies]] === Requirements [.small]#xref:web/webmvc-view/mvc-script.adoc#mvc-view-script-dependencies[See equivalent in the Servlet stack]# You need to have the script engine on your classpath, the details of which vary by script engine: * https://www.jruby.org[JRuby] should be added as a dependency for Ruby support. * https://www.jython.org[Jython] should be added as a dependency for Python support. [[webflux-view-script-integrate]] === Script Templates [.small]#xref:web/webmvc-view/mvc-script.adoc#mvc-view-script-integrate[See equivalent in the Servlet stack]# You can declare a `ScriptTemplateConfigurer` bean to specify the script engine to use, the script files to load, what function to call to render templates, and so on. The following example uses the Jython Python engine: [tabs] ====== Java:: + [source,java,indent=0,subs="verbatim,quotes"] ---- @Configuration public class WebConfig implements WebFluxConfigurer { @Override public void configureViewResolvers(ViewResolverRegistry registry) { registry.scriptTemplate(); } @Bean public ScriptTemplateConfigurer configurer() { ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer(); configurer.setEngineName("jython"); configurer.setScripts("render.py"); configurer.setRenderFunction("render"); return configurer; } } ---- Kotlin:: + [source,kotlin,indent=0,subs="verbatim,quotes"] ---- @Configuration class WebConfig : WebFluxConfigurer { override fun configureViewResolvers(registry: ViewResolverRegistry) { registry.scriptTemplate() } @Bean fun configurer() = ScriptTemplateConfigurer().apply { engineName = "jython" setScripts("render.py") renderFunction = "render" } } ---- ====== The `render` function is called with the following parameters: * `String template`: The template content * `Map model`: The view model * `RenderingContext renderingContext`: The {spring-framework-api}/web/servlet/view/script/RenderingContext.html[`RenderingContext`] that gives access to the application context, the locale, the template loader, and the URL Check out the Spring Framework unit tests, {spring-framework-code}/spring-webflux/src/test/java/org/springframework/web/reactive/result/view/script[Java], and {spring-framework-code}/spring-webflux/src/test/resources/org/springframework/web/reactive/result/view/script[resources], for more configuration examples. [[webflux-view-fragments]] == HTML Fragment [.small]#xref:web/webmvc-view/mvc-fragments.adoc[See equivalent in the Servlet stack]# https://htmx.org/[HTMX] and https://turbo.hotwired.dev/[Hotwire Turbo] emphasize an HTML-over-the-wire approach where clients receive server updates in HTML rather than in JSON. This allows the benefits of an SPA (single page app) without having to write much or even any JavaScript. For a good overview and to learn more, please visit their respective websites. In Spring WebFlux, view rendering typically involves specifying one view and one model. However, in HTML-over-the-wire a common capability is to send multiple HTML fragments that the browser can use to update different parts of the page. For this, controller methods can return `Collection`. For example: [tabs] ====== Java:: + [source,java,indent=0,subs="verbatim,quotes"] ---- @GetMapping List handle() { return List.of(Fragment.create("posts"), Fragment.create("comments")); } ---- Kotlin:: + [source,kotlin,indent=0,subs="verbatim,quotes"] ---- @GetMapping fun handle(): List { return listOf(Fragment.create("posts"), Fragment.create("comments")) } ---- ====== The same can be done also by returning the dedicated type `FragmentsRendering`: [tabs] ====== Java:: + [source,java,indent=0,subs="verbatim,quotes"] ---- @GetMapping FragmentsRendering handle() { return FragmentsRendering.fragment("posts").fragment("comments").build(); } ---- Kotlin:: + [source,kotlin,indent=0,subs="verbatim,quotes"] ---- @GetMapping fun handle(): FragmentsRendering { return FragmentsRendering.fragment("posts").fragment("comments").build() } ---- ====== Each fragment can have an independent model, and that model inherits attributes from the shared model for the request. HTMX and Hotwire Turbo support streaming updates over SSE (server-sent events). A controller can create `FragmentsRendering` with a `Flux`, or with any other reactive producer adaptable to a Reactive Streams `Publisher` via `ReactiveAdapterRegistry`. It is also possible to return `Flux` directly without the `FragmentsRendering` wrapper. [[webflux-view-httpmessagewriter]] == JSON and XML [.small]#xref:web/webmvc-view/mvc-jackson.adoc[See equivalent in the Servlet stack]# For xref:web/webflux/dispatcher-handler.adoc#webflux-multiple-representations[Content Negotiation] purposes, it is useful to be able to alternate between rendering a model with an HTML template or as other formats (such as JSON or XML), depending on the content type requested by the client. To support doing so, Spring WebFlux provides the `HttpMessageWriterView`, which you can use to plug in any of the available xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] from `spring-web`, such as `JacksonJsonEncoder`, `JacksonSmileEncoder`, or `Jaxb2XmlEncoder`. Unlike other view technologies, `HttpMessageWriterView` does not require a `ViewResolver` but is instead xref:web/webflux/config.adoc#webflux-config-view-resolvers[configured] as a default view. You can configure one or more such default views, wrapping different `HttpMessageWriter` instances or `Encoder` instances. The one that matches the requested content type is used at runtime. In most cases, a model contains multiple attributes. To determine which one to serialize, you can configure `HttpMessageWriterView` with the name of the model attribute to use for rendering. If the model contains only one attribute, that one is used.