Renderers

This page explains the concept of renderers, how to configure them and which renderers Magnolia provides out of the box.

Overview

A renderer produces output such as HTML or text based on the template definition, the template script and JCR content. 

In summary, a renderer does the following things:

• Creates the model.
• Gets context objects.
• Executes template scripts.

 The SPA renderer uses different techniques to render a page.

The rendering process is executed by the RenderingFilter. The result of the renderer is written to the ServletOutputStream and sent to the browser. For further details see Rendering content.

Magnolia provides the following renderers out of the box: 

• FreemarkerRenderer
• SiteAwareRendererWrapper 
• SpaRenderer

You can also implement your own custom renderer. To use a renderer, you must configure it either using YAML or in the JCR configuration workspace.

Configuring a renderer

To make a renderer available, you must configure it in the renderers folder of any module either using YAML, or in the JCR configuration workspace.

Once configured, you can:

• Decorate the renderer definition.
• Reuse the renderer definition as a base for a new renderer using YAML inherit.
• Use the YAML include directive if the definition is YAML based.

View your renderer definitions in the Definitions app.

Example:

class: info.magnolia.rendering.renderer.FreemarkerRenderer
contextAttributes:
  cms:
    componentClass: info.magnolia.templating.freemarker.Directives
    name: cms
  cmsfn:
    componentClass: info.magnolia.templating.functions.TemplatingFunctions
    name: cmsfn

Properties:

title: test-page
templateScript: /test-custom-renderers/templates/pages/test-page.ftl
renderType: foobar

Renderers provided by Magnolia

Magnolia provides a number of renderers out-of-the-box. 

Note that magnolia-rendering is available in every preconfigured Magnolia bundle or webapp, whereas  magnolia-site is available in every preconfigured Magnolia bundle or webapp except magnolia-empty-webapp.

Freemarker renderer

The freemarker renderer is used to render pages relying on templates with freemarker-based template scripts. The freemarker renderer can be considered as the standard Magnolia renderer. It is also the base for the site aware renderer.

The implementation class is FreemarkerRenderer. 

Freemarker exception handling

Freemarker exceptions render differently on the author and public instances. On author, Freemarker exceptions show the stack trace in a yellow block with red text, and on public errors are hidden and logged.

This behavior is controlled by ModeDependentTemplateExceptionHandler registered in /server/rendering/freemarker/templateExceptionHandler. You can extend this class to fine-grain behavior.

Site aware renderers

A site aware renderer resolves the site definition related to the given request, and it merges the template definition of the requested page with the template prototype from the site definition.

The  magnolia-site module adds the  sitefn  context attribute to the freemarker renderer configuration, and it configures the site site-aware renderer at /modules/site/renderers.

Site aware renderers are implemented by the class SiteAwareRendererWrapper. It is a wrapper that relies on another already existing renderer. It comes with the property wrappedRendererType, which must be configured. The value of this property is the name of the wrapped renderer.

SPA renderer

The SPA (Single-Page Application) renderer produces template annotations, which the Pages app transforms into the green toolbars – editable page elements.

The implementation class is SpaRenderer.

Currently, the following functionalities are not supported in SPA rendering:

• component autogeneration
• component inheritance
• component personalization
• fragment definition
• area-in-area nesting

JavaScript renderers

Two additional JavaScript libraries are provided by Magnolia to help render SPA pages in the Angular and ReactJS front-end frameworks.

Repository link:  https://git.magnolia-cms.com/scm/modules/frontend-helpers.git

Others

The renderers described above are the most frequently used Magnolia renderers and cater to many use cases.

The following renderers are used for special cases.

Creating a custom renderer

To create your own renderer, extend AbstractRenderer. This convenience class supports typical functionality such as setting context attributes and executing a rendering model. It sets up the context by providing the following objects:

• content
• def
• state
• model
• actionResult

See mustache-rendering for a detailed example.