Rendering Templates #

This functionality is still under construction and the documentation may change frequently.

You can author templates using the Freemarker template language. Freemarker was chosen as the default template engine because it is well supported in the IntelliJ IDEA environment.

By default, the diego.templates.TemplateEngine will look for *.ftl files in the src/main/resources/templates directory of your project.

To render a template, just call TemplateEngine#render() and specify the name of the template:

@Inject TemplateEngine templateEngine

String result = templateEngine.render("greet.ftl", [greeting: "Hello, world!"])

<!-- src/main/resources/templates/greet.ftl -->
<h1>
    ${greeting}
</h1>

Configuring template locations #

If you wish to change the default template directory, use the app.templates.dir property in the application.conf file:

# Configure templates
app.templates {
	# The directory from which templates should be loaded during development
	dir = "file:my/templates/dir"
}

You might have noticed the file: scheme included in the template directory. This tells the template loader to load templates from the file system. This is very useful during development, since you won’t need to rebuild the application in order to see changes to your templates.

In production you can use the classpath: scheme to tell the template loader to search the class path for templates:

app.templates.dir = "classpath:/templates"

Rendering views #

The HttpServerResponse class now has a render() method that matches the signature of the TemplateEngine#render method. The main difference being, when using the HttpServerResponse#render() method, the template specified must reside in the ${app.templates.dir}/views directory of your project.

Template variables #

In addition to entries in the Map used when calling response.render(), any metadata you stored on your request using request.put() will also be available in your templates. You also have access to a lightweight version of the HttpServerRequest in the form of RequestModel where you can access request parameters and the request path.

Note: Template variables are merged into a single Map object. Keys with the same name will be replaced

Utility methods #

The framework ships with a few utility methods for use in your templates:

The json method converts a given object to a JSON string. Useful for inline scripts:

<script>
	const user = JSON.parse('${json(user)}');
</script>

Supplying your own utility methods #

To supply your own utility methods, access the main freemarker.template.Configuration object and utilize the setSharedVariable() method. For example, in your main application:

class MyApp extends Application {
    
    @Inject
    void configureTemplateEngine(Configuration configuration, TemplateMethodModelEx fooMethod) {
        configuration.setSharedVariable("foo", fooMethod)
    }
}

The fooMethod must be an instance of TemplateMethodModelEx.

The value you supply for the first argument to the setSharedVariable() method will be used to invoke the method in your template. For the example above, you would call ${foo()} to invoke your custom method.

If you wish to override any of the built-in utility methods with your own, simply supply the same name as the name of the method you wish to override in your configuration:

configuration.setSharedVariable("json", require(com.myapp.MyCustomJsonRenderer))

Since the Configuration object is a shared singleton, you can use it to customize how the underlying Freemarker template renderer works. Any changes you make to this object will be propagated throughout the application.

Next: Databases