Custom Renderers

If available renderers don’t fit your needs, the IO add-on provides an SPI to register your custom renderers. There are three options to provide your own renderer: static template, dynamic template or without template.

Static template

In this case, templates are loaded from files within the META-INF/templates directory. You need to extend three classes: AbstractBaseStaticTemplateLoader, AbstractBaseTemplate and AbstractTemplateRenderer.

  • The template loader loads the template from the corresponding resource in META-INF/templates directory.
  • The template have all information necessary to render a model.
  • The renderer is able to render a model into an OutputStream, using the template information.

Dynamic template

In the case of a dynamic template, your loader will completely handle the loading logic. Implement the TemplateLoader interface:

public class MyDynamicTemplateLoader implements TemplateLoader<MyTemplate> {
    public MyTemplate load(String name) throws Exception {
        // Gets your template from anywhere
        return myTemplate;

    Set<String> names() {
        // Returns all the templates you know
        return names;

    boolean contains(String name) {
        // Checks if you know this template
        return bool;

    public String templateRenderer() {
        // Returns the name of the associated renderer
        return "MyTemplateRenderer";

Without template

A renderer without template doesn’t need any information to render the model. It is often the case of specific renderers that are not meant to be reusable. Extend AbstractBaseRenderer and annotate it with @Named.

public class CustomRenderer extends AbstractBaseRenderer {
    public void render(OutputStream outputStream, Object model) {
        render(outputStream, model, null, null);

    public void render(OutputStream outputStream, Object model, String mimeType, Map<String, Object> parameters) {
        try {
            outputStream.write("Hello World!".getBytes());
        } catch (IOException e) {
            throw new RuntimeException(e);

You can inject it as usual:

public class SomeClass {
	private Renderer renderer;

On this page

Edit this page