Rossen Stoyanchev
8 years ago
3 changed files with 331 additions and 38 deletions
@ -0,0 +1,288 @@ |
|||||||
|
[[webflux-view]] |
||||||
|
= View Technologies |
||||||
|
[.small]#<<web.adoc#mvc-view,Same in Spring MVC>># |
||||||
|
|
||||||
|
The use of view technologies in Spring WebFlux is pluggable, whether you decide to |
||||||
|
use Thymeleaf, FreeMarker, or other, is primarily a matter of a configuration change. |
||||||
|
This chapter covers view technologies integrated with Spring WebFlux. We assume you are |
||||||
|
already familiar with <<webflux-viewresolution>>. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-view-thymeleaf]] |
||||||
|
== Thymeleaf |
||||||
|
[.small]#<<web.adoc#mvc-view-thymeleaf,Same in Spring MVC>># |
||||||
|
|
||||||
|
Thymeleaf is 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, e.g. by 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 |
||||||
|
http://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 |
||||||
|
http://www.thymeleaf.org/documentation.html[Thymeleaf+Spring] and the WebFlux integration |
||||||
|
http://forum.thymeleaf.org/Thymeleaf-3-0-8-JUST-PUBLISHED-td4030687.html[announcement]. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-view-freemarker]] |
||||||
|
== FreeMarker |
||||||
|
[.small]#<<web.adoc#mvc-view-freemarker,Same in Spring MVC>># |
||||||
|
|
||||||
|
http://www.freemarker.org[Apache FreeMarker] is a template engine for generating any |
||||||
|
kind of text output from HTML to email, and others. The Spring Framework has a built-in |
||||||
|
integration for using Spring WebFlux with FreeMarker templates. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-view-freemarker-contextconfig]] |
||||||
|
=== View config |
||||||
|
[.small]#<<web.adoc#mvc-view-freemarker-contextconfig,Same in Spring MVC>># |
||||||
|
|
||||||
|
To configure FreeMarker as a view technology: |
||||||
|
|
||||||
|
[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"); |
||||||
|
return configurer; |
||||||
|
} |
||||||
|
} |
||||||
|
---- |
||||||
|
|
||||||
|
Your templates need to be stored in the directory specified by the `FreeMarkerConfigurer` |
||||||
|
shown above. Given the above configuration if your controller returns the view name |
||||||
|
"welcome" then the resolver will look for the |
||||||
|
`classpath:/templates/freemarker/welcome.ftl` template. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-views-freemarker]] |
||||||
|
=== FreeMarker config |
||||||
|
[.small]#<<web.adoc#mvc-views-freemarker,Same in Spring MVC>># |
||||||
|
|
||||||
|
FreeMarker 'Settings' and 'SharedVariables' can be passed directly to the FreeMarker |
||||||
|
`Configuration` object 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`. |
||||||
|
|
||||||
|
[source,java,indent=0] |
||||||
|
[subs="verbatim,quotes"] |
||||||
|
---- |
||||||
|
@Configuration |
||||||
|
@EnableWebFlux |
||||||
|
public class WebConfig implements WebFluxConfigurer { |
||||||
|
|
||||||
|
// ... |
||||||
|
|
||||||
|
@Bean |
||||||
|
public FreeMarkerConfigurer freeMarkerConfigurer() { |
||||||
|
Map<String, Object> variables = new HashMap<>(); |
||||||
|
variables.put("xml_escape", new XmlEscape()); |
||||||
|
|
||||||
|
FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); |
||||||
|
configurer.setTemplateLoaderPath("classpath:/templates"); |
||||||
|
configurer.setFreemarkerVariables(variables); |
||||||
|
return configurer; |
||||||
|
} |
||||||
|
} |
||||||
|
---- |
||||||
|
|
||||||
|
See the FreeMarker documentation for details of settings and variables as they apply to |
||||||
|
the `Configuration` object. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-view-script]] |
||||||
|
== Script Views |
||||||
|
[.small]#<<web.adoc#mvc-view-script,Same in Spring MVC>># |
||||||
|
|
||||||
|
The Spring Framework has a built-in integration for using Spring WebFlux with any |
||||||
|
templating library that can run on top of the |
||||||
|
https://www.jcp.org/en/jsr/detail?id=223[JSR-223] Java scripting engine. Below is a list |
||||||
|
of templating libraries we've tested on different script engines: |
||||||
|
|
||||||
|
[horizontal] |
||||||
|
http://handlebarsjs.com/[Handlebars] :: http://openjdk.java.net/projects/nashorn/[Nashorn] |
||||||
|
https://mustache.github.io/[Mustache] :: http://openjdk.java.net/projects/nashorn/[Nashorn] |
||||||
|
http://facebook.github.io/react/[React] :: http://openjdk.java.net/projects/nashorn/[Nashorn] |
||||||
|
http://www.embeddedjs.com/[EJS] :: http://openjdk.java.net/projects/nashorn/[Nashorn] |
||||||
|
http://www.stuartellis.eu/articles/erb/[ERB] :: http://jruby.org[JRuby] |
||||||
|
https://docs.python.org/2/library/string.html#template-strings[String templates] :: http://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]#<<web.adoc#mvc-view-script-dependencies,Same in Spring MVC>># |
||||||
|
|
||||||
|
You need to have the script engine on your classpath: |
||||||
|
|
||||||
|
* http://openjdk.java.net/projects/nashorn/[Nashorn] JavaScript engine is provided with |
||||||
|
Java 8+. Using the latest update release available is highly recommended. |
||||||
|
* http://jruby.org[JRuby] should be added as a dependency for Ruby support. |
||||||
|
* http://www.jython.org[Jython] should be added as a dependency for Python support. |
||||||
|
|
||||||
|
You need to have the script templating library. One way to do that for Javascript is |
||||||
|
through http://www.webjars.org/[WebJars]. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-view-script-integrate]] |
||||||
|
=== Script templates |
||||||
|
[.small]#<<web.adoc#mvc-view-script-integrate,Same in Spring MVC>># |
||||||
|
|
||||||
|
Declare a `ScriptTemplateConfigurer` bean in order to specify the script engine to use, |
||||||
|
the script files to load, what function to call to render templates, and so on. |
||||||
|
Below is an example with Mustache templates and the Nashorn JavaScript engine: |
||||||
|
|
||||||
|
[source,java,indent=0] |
||||||
|
[subs="verbatim,quotes"] |
||||||
|
---- |
||||||
|
@Configuration |
||||||
|
@EnableWebFlux |
||||||
|
public class WebConfig implements WebFluxConfigurer { |
||||||
|
|
||||||
|
@Override |
||||||
|
public void configureViewResolvers(ViewResolverRegistry registry) { |
||||||
|
registry.scriptTemplate(); |
||||||
|
} |
||||||
|
|
||||||
|
@Bean |
||||||
|
public ScriptTemplateConfigurer configurer() { |
||||||
|
ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer(); |
||||||
|
configurer.setEngineName("nashorn"); |
||||||
|
configurer.setScripts("mustache.js"); |
||||||
|
configurer.setRenderObject("Mustache"); |
||||||
|
configurer.setRenderFunction("render"); |
||||||
|
return configurer; |
||||||
|
} |
||||||
|
} |
||||||
|
---- |
||||||
|
|
||||||
|
The render function is called with the following parameters: |
||||||
|
|
||||||
|
* `String template`: the template content |
||||||
|
* `Map model`: the view model |
||||||
|
* `String url`: the template url (since 4.2.2) |
||||||
|
|
||||||
|
`Mustache.render()` is natively compatible with this signature, so you can call it directly. |
||||||
|
|
||||||
|
If your templating technology requires some customization, you may provide a script that |
||||||
|
implements a custom render function. For example, http://handlebarsjs.com[Handlerbars] |
||||||
|
needs to compile templates before using them, and requires a |
||||||
|
http://en.wikipedia.org/wiki/Polyfill[polyfill] in order to emulate some |
||||||
|
browser facilities not available in the server-side script engine. |
||||||
|
|
||||||
|
[source,java,indent=0] |
||||||
|
[subs="verbatim,quotes"] |
||||||
|
---- |
||||||
|
@Configuration |
||||||
|
@EnableWebMvc |
||||||
|
public class WebConfig implements WebFluxConfigurer { |
||||||
|
|
||||||
|
@Override |
||||||
|
public void configureViewResolvers(ViewResolverRegistry registry) { |
||||||
|
registry.scriptTemplate(); |
||||||
|
} |
||||||
|
|
||||||
|
@Bean |
||||||
|
public ScriptTemplateConfigurer configurer() { |
||||||
|
ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer(); |
||||||
|
configurer.setEngineName("nashorn"); |
||||||
|
configurer.setScripts("polyfill.js", "handlebars.js", "render.js"); |
||||||
|
configurer.setRenderFunction("render"); |
||||||
|
configurer.setSharedEngine(false); |
||||||
|
return configurer; |
||||||
|
} |
||||||
|
} |
||||||
|
---- |
||||||
|
|
||||||
|
[NOTE] |
||||||
|
==== |
||||||
|
Setting the `sharedEngine` property to `false` is required when using non thread-safe |
||||||
|
script engines with templating libraries not designed for concurrency, like Handlebars or |
||||||
|
React running on Nashorn for example. In that case, Java 8u60 or greater is required due |
||||||
|
to https://bugs.openjdk.java.net/browse/JDK-8076099[this bug]. |
||||||
|
==== |
||||||
|
|
||||||
|
`polyfill.js` only defines the `window` object needed by Handlebars to run properly: |
||||||
|
|
||||||
|
[source,javascript,indent=0] |
||||||
|
[subs="verbatim,quotes"] |
||||||
|
---- |
||||||
|
var window = {}; |
||||||
|
---- |
||||||
|
|
||||||
|
This basic `render.js` implementation compiles the template before using it. A production |
||||||
|
ready implementation should also store and reused cached templates / pre-compiled templates. |
||||||
|
This can be done on the script side, as well as any customization you need (managing |
||||||
|
template engine configuration for example). |
||||||
|
|
||||||
|
[source,javascript,indent=0] |
||||||
|
[subs="verbatim,quotes"] |
||||||
|
---- |
||||||
|
function render(template, model) { |
||||||
|
var compiledTemplate = Handlebars.compile(template); |
||||||
|
return compiledTemplate(model); |
||||||
|
} |
||||||
|
---- |
||||||
|
|
||||||
|
Check out the Spring Framework unit tests, |
||||||
|
https://github.com/spring-projects/spring-framework/tree/master/spring-webflux/src/test/java/org/springframework/web/reactive/result/view/script[java], and |
||||||
|
https://github.com/spring-projects/spring-framework/tree/master/spring-webflux/src/test/resources/org/springframework/web/reactive/result/view/script[resources], |
||||||
|
for more configuration examples. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[[webflux-view-httpmessagewriter]] |
||||||
|
== JSON, XML |
||||||
|
[.small]#<<web.adoc#mvc-view-jackson,Same in Spring MVC>># |
||||||
|
|
||||||
|
For <<webflux-multiple-representations>> 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 this Spring WebFlux |
||||||
|
provides the `HttpMessageWriterView` that can be used to plug in any of the available |
||||||
|
<<webflux-codecs>> from `spring-web` such as `Jackson2JsonEncoder`, |
||||||
|
`Jackson2SmileEncoder`, or `Jaxb2XmlEncoder`. |
||||||
|
|
||||||
|
Unlike other view technologies, `HttpMessageWriterView` does not require a `ViewResolver`, |
||||||
|
but instead is <<webflux-config-view-resolvers,configured>> as a default view. You can |
||||||
|
configure one more such default views, wrapping different ``HttpMessageWriter``'s or |
||||||
|
``Encoder``'s. The one that matches the requested content type is used at runtime. |
||||||
|
|
||||||
|
In most cases a model will contain multiple attributes. In order to determine which one |
||||||
|
to serialize, `HttpMessageWriterView` can be configured with the name of the model |
||||||
|
attribute to use render, of if the model contains only one attribute, it will be used. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Loading…
Reference in new issue