FreeMarker is a “template engine”; a generic tool to generate text output (anything from HTML to autogenerated source code) based on templates. It’s a Java package, a class library for Java programmers. It’s not an application for end-users in itself, but something that programmers can embed into their products.

It is the “generic” nature of Freemarker that trips up java web developers. Freemarker by default does not provide any facilities to allow default HTML-escaping of content – a necessity if you want to attempt to prevent Cross-Site Scripting attacks on your web applications. Yes I know that it has the ?html built-in, and that you can wrap blocks of text in <#escape x as x?html> directives, but you have to remember to do that on each page.

What if there was another way?

The class below is a Freemarker TemplateLoader that automatically wraps each loaded template with the HTML-escape directive. Now there is no need to remember to do that in your templates. You can find it being used in my example project on GitHub.

import freemarker.cache.TemplateLoader;
import org.apache.commons.io.IOUtils;

import java.io.IOException;
import java.io.Reader;
import java.io.StringReader;

public class HtmlTemplateLoader implements TemplateLoader {

    public static final String ESCAPE_PREFIX = "<#ftl strip_whitespace=true><#escape x as x?html>";
    public static final String ESCAPE_SUFFIX = "</#escape>";

    private final TemplateLoader delegate;

    public HtmlTemplateLoader(TemplateLoader delegate) {
        this.delegate = delegate;
    }

    @Override
    public Object findTemplateSource(String name) throws IOException {
        return delegate.findTemplateSource(name);
    }

    @Override
    public long getLastModified(Object templateSource) {
        return delegate.getLastModified(templateSource);
    }

    @Override
    public Reader getReader(Object templateSource, String encoding) throws IOException {
        Reader reader = delegate.getReader(templateSource, encoding);
        try {
            String templateText = IOUtils.toString(reader);
            return new StringReader(ESCAPE_PREFIX + templateText + ESCAPE_SUFFIX);
        } finally {
            IOUtils.closeQuietly(reader);
        }
    }

    @Override
    public void closeTemplateSource(Object templateSource) throws IOException {
        delegate.closeTemplateSource(templateSource);
    }
}

To wire this up using SpringFramework’s Freemarker support you do have to take another step and extend its FreeMarkerConfigurer to register the HtmlTemplateLoader as the one to use for view resolution and rendering. If on the other hand you don’t use Spring then you have one less bit of code to maintain.

import freemarker.cache.TemplateLoader;
import org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer;

import java.util.List;

public class HtmlFreeMarkerConfigurer extends FreeMarkerConfigurer {

    @Override
    protected TemplateLoader getAggregateTemplateLoader(List<TemplateLoader> templateLoaders) {
        logger.info("Using HtmlTemplateLoader to enforce HTML-safe content");
        return new HtmlTemplateLoader(super.getAggregateTemplateLoader(templateLoaders));
    }
}

if try_require('kramdown', 'kramdown')
  Webby::Filters.register :kramdown do |input|
    Kramdown::Document.new(input, :parse_block_html => true).to_html
  end
else
  Webby::Filters.register :kramdown do |input|
    raise Webby::Error, "'kramdown' must be installed to use the kramdown filter"
  end
end

Simply paste the above into a file called kramdown.rb in your project’s lib directory and then you can specify filter: kramdown in your webby templates.