Rendering Templates #

By default, templates are authored using the Freemarker template language. Freemarker was chosen as the default template engine because it is well supported in the IntelliJ IDEA environment.

Template locations #

In development, the diego.templates.TemplateEngine will look for *.ftl files in {diego.resourceBase}/templates in your project directory, then it will search the Classpath for a /templates directory. In any other environment, it will search the Classpath only.

Using the template engine directly #

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

public class UsingTemplateEngine {
    @Inject public TemplateEngine templateEngine;
    
    public void render(String message) {
        final Map<String, Object> data = new HashMap<>();
        data.put("message", message);
        String result = templateEngine.render("greet", message);
        System.out.println(result);
    }
}

<!-- {diego.resourceBase}/templates/greet.ftl -->
<h1>
    ${greeting}
</h1>

Rendering views #

Calling the Context.renderView() or returning a ModelAndViewResult and supplying a template name will render a template from the {diego.resourceBase}/templates/views directory (or the /templates/views location in the Class path if in production):

// Express-style routing
app.get("/", ctx -> ctx.renderView("index") ); // Renders the index.ftl file in {diego.resourceBase}/templates/views

// Controller action
@GET
public Result index() {
    return Results.view("index");
}

Template variables #

Any data you stored on the current HTTP request context using Context#put() will be available in your templates. Additionally, the framework adds some variables to the template that can be useful when rendering views for the client:

Note: Template variables are merged into a single Map object. Keys with the same name will be replaced, with the framework’s implicit variables. Template variable are also only available in views.

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 implements WebMvcConfiguration {
    
    @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", load(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.

Live Reloading Templates #

When developing web applications, it’s useful to have the browser automatically reload whenever your assets (CSS, JavaScript and templates) change. If you wish to enable this functionality for your views, include the following snippet in your templates:

<script type="text/javascript" src="/@diego/reload-client.js"></script>

Any changes to static assets in the {diego.resourceBase}/public or {dieog.resourceBase}/templates directories will trigger a page reload or CSS style injection.

Templates will not be reloaded if there is an error in template compilation, so check the console if you don’t see your changes being reflected.

Configuration #

# Use the default or implement your own TemplateEngine if you prefer
diego.templates.engine = "diego.templates.freemarker.FreemarkerModule"

Next: Diego JDBC