Update and improve script templating documentation

Issue: SPR-16447

spring-webflux/src/main/java/org/springframework/web/reactive/result/view/script/RenderingContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,7 +22,9 @@ import java.util.function.Function;
 import org.springframework.context.ApplicationContext;
 
 /**
- * Context passed to {@link ScriptTemplateView} render function.
+ * Context passed to {@link ScriptTemplateView} render function in order to make
+ * the application context, the locale, the template loader and the url available on
+ * scripting side.
  *
  * @author Sebastien Deleuze
  * @since 5.0
@@ -38,6 +40,15 @@ public class RenderingContext {
 	private final String url;
 
 
+	/**
+	 * Create a new {@code RenderingContext}.
+	 *
+	 * @param applicationContext the application context
+	 * @param locale the locale of the rendered template
+	 * @param templateLoader a function that takes a template path as input and returns
+	 * the template content as a String
+	 * @param url the URL of the rendered template
+	 */
 	public RenderingContext(ApplicationContext applicationContext, Locale locale,
 			Function<String, String> templateLoader, String url) {
 
@@ -48,18 +59,31 @@ public class RenderingContext {
 	}
 
 
+	/**
+	 * Return the application context.
+	 */
 	public ApplicationContext getApplicationContext() {
 		return this.applicationContext;
 	}
 
+	/**
+	 * Return the locale of the rendered template.
+	 */
 	public Locale getLocale() {
 		return this.locale;
 	}
 
+	/**
+	 * Return a function that takes a template path as input and returns the template
+	 * content as a String.
+	 */
 	public Function<String, String> getTemplateLoader() {
 		return this.templateLoader;
 	}
 
+	/**
+	 * Return the URL of the rendered template.
+	 */
 	public String getUrl() {
 		return this.url;
 	}

spring-webmvc/src/main/java/org/springframework/web/servlet/view/script/RenderingContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,7 +22,9 @@ import java.util.function.Function;
 import org.springframework.context.ApplicationContext;
 
 /**
- * Context passed to {@link ScriptTemplateView} render function.
+ * Context passed to {@link ScriptTemplateView} render function in order to make
+ * the application context, the locale, the template loader and the url available on
+ * scripting side.
  *
  * @author Sebastien Deleuze
  * @since 5.0
@@ -38,6 +40,15 @@ public class RenderingContext {
 	private final String url;
 
 
+	/**
+	 * Create a new {@code RenderingContext}.
+	 *
+	 * @param applicationContext the application context
+	 * @param locale the locale of the rendered template
+	 * @param templateLoader a function that takes a template path as input and returns
+	 * the template content as a String
+	 * @param url the URL of the rendered template
+	 */
 	public RenderingContext(ApplicationContext applicationContext, Locale locale,
 			Function<String, String> templateLoader, String url) {
 
@@ -48,18 +59,31 @@ public class RenderingContext {
 	}
 
 
+	/**
+	 * Return the application context.
+	 */
 	public ApplicationContext getApplicationContext() {
 		return this.applicationContext;
 	}
 
+	/**
+	 * Return the locale of the rendered template.
+	 */
 	public Locale getLocale() {
 		return this.locale;
 	}
 
+	/**
+	 * Return a function that takes a template path as input and returns the template
+	 * content as a String.
+	 */
 	public Function<String, String> getTemplateLoader() {
 		return this.templateLoader;
 	}
 
+	/**
+	 * Return the URL of the rendered template.
+	 */
 	public String getUrl() {
 		return this.url;
 	}

src/docs/asciidoc/web/webflux-view.adoc

@@ -131,6 +131,7 @@ http://facebook.github.io/react/[React] :: http://openjdk.java.net/projects/nash
 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]
+https://github.com/sdeleuze/kotlin-script-templating[Kotlin Script templating] :: http://kotlinlang.org/[Kotlin]
 
 [TIP]
 ====
@@ -150,6 +151,10 @@ You need to have the script engine on your classpath:
 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.
+* `org.jetbrains.kotlin:kotlin-script-util` dependency and a `META-INF/services/javax.script.ScriptEngineFactory`
+ file containing a `org.jetbrains.kotlin.script.jsr223.KotlinJsr223JvmLocalScriptEngineFactory`
+ line should be added for Kotlin script support, see
+ https://github.com/sdeleuze/kotlin-script-templating[this example] for more details.
 
 You need to have the script templating library. One way to do that for Javascript is
 through http://www.webjars.org/[WebJars].
@@ -192,7 +197,10 @@ 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)
+* `RenderingContext renderingContext`: the
+  {api-spring-framework}/web/servlet/view/script/RenderingContext.html[RenderingContext]
+  that gives access to the application context, the locale, the template loader and the
+  url (since 5.0)
 
 `Mustache.render()` is natively compatible with this signature, so you can call it directly.
 

src/docs/asciidoc/web/webmvc-view.adoc

@@ -551,6 +551,7 @@ http://facebook.github.io/react/[React] :: http://openjdk.java.net/projects/nash
 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]
+https://github.com/sdeleuze/kotlin-script-templating[Kotlin Script templating] :: http://kotlinlang.org/[Kotlin]
 
 [TIP]
 ====
@@ -570,6 +571,10 @@ You need to have the script engine on your classpath:
 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.
+* `org.jetbrains.kotlin:kotlin-script-util` dependency and a `META-INF/services/javax.script.ScriptEngineFactory`
+ file containing a `org.jetbrains.kotlin.script.jsr223.KotlinJsr223JvmLocalScriptEngineFactory`
+ line should be added for Kotlin script support, see
+ https://github.com/sdeleuze/kotlin-script-templating[this example] for more details.
 
 You need to have the script templating library. One way to do that for Javascript is
 through http://www.webjars.org/[WebJars].
@@ -660,7 +665,10 @@ 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)
+* `RenderingContext renderingContext`: the
+  {api-spring-framework}/web/servlet/view/script/RenderingContext.html[RenderingContext]
+  that gives access to the application context, the locale, the template loader and the
+  url (since 5.0)
 
 `Mustache.render()` is natively compatible with this signature, so you can call it directly.