Page tree
Skip to end of metadata
Go to start of metadata

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

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:

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
  • JspRenderer
  • SiteAwareRendererWrapper 

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:

renderer-test-module/renderers/foobar.yaml
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
Node nameValue

 modules


 renderer-test-module


  renderers


 foobar


 contextAttributes


 cms


 componentClass

info.magnolia.templating.freemarker.Directives

 name

cms

 cmsfn


 componentClass

info.magnolia.templating.functions.TemplatingFunctions

 name

cmsfn

Properties:



name

The name of the renderer. In JCR it is the node name, in YAML it is the file name. (In the example above, the name is foobar.)

The renderer name is used to reference a renderer within a template definition.

 Click here to see how to reference a renderer in a template definition
/test-custom-renderers/templates/pages/test-page.yaml
title: test-page
templateScript: /test-custom-renderers/templates/pages/test-page.ftl
renderType: foobar
class

The fully qualified class name of the class that must implement the interface Renderer.

contextAttributesA map to register components that are injected into the rendering context. The components can be used within the template scripts with their given names.

componentClass

The fully qualified class name of the context attribute component.

name

The name of the component to add to the context. Use this name to reference the component in a template script.

Renderers provided by Magnolia

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

Use the default Magnolia renderers as a base. Extend them to define your own new renderers using YAML inherit or similar techniques to reuse the configuration.

RendererProvided by the moduleConfiguration
Freemarker renderermagnolia-rendering /modules/rendering/renderers/freemarker
JSP renderermagnolia-rendering /modules/rendering/renderers/jsp
Site aware renderer for freemarkermagnolia-site/modules/site/renderers/site
Site aware renderer for JSPmagnolia-site/modules/site/renderers/site-jsp

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

 Click here to expand to see the configuration of the freemarker renderer
Node nameValue

 modules


 rendering


 renderers


 freemarker


 contextAttributes


 cms


 componentClass

info.magnolia.templating.freemarker.Directives

 name

cms

 cmsfn


 componentClass

info.magnolia.templating.functions.TemplatingFunctions

 name

cmsfn

 damfn


 componentClass

info.magnolia.dam.templating.functions.DamTemplatingFunctions

 name

damfn

 searchfn


 componentClass

info.magnolia.templating.functions.SearchTemplatingFunctions

 name

searchfn

 catfn


 componentClass

info.magnolia.module.categorization.functions.CategorizationTemplatingFunctions

 name

catfn

 class

info.magnolia.rendering.renderer.FreemarkerRenderer

Some parts of the configuration are added by modules which provide components registered in contextAttributes.

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.

Node nameValue

 server


 rendering


 freemarker


 templateExceptionHandler


 class

info.magnolia.freemarker.ModeDependentTemplateExceptionHandler

JSP renderer

Use this renderer if your template scripts are written in JSPThe implementation class is JspRenderer.

 Click here to expand to see the configuration of the JSP renderer
Node nameValue

 modules


 rendering


 renderers


 jsp


 contextAttributes


 cmsfn


 componentClass

info.magnolia.templating.functions.TemplatingFunctions

 name

cmsfn

Some parts of the configuration are added by modules which provide components registered in contextAttributes.

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 two site aware renderers at /modules/site/renderers:

  • site
  • site-jsp

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.

 Click here to expand to see the configuration of the site aware renderers
Node nameValue

 modules


 site


 renderers


  site


 class

info.magnolia.module.site.renderer.SiteAwareRendererWrapper

 wrappedRendererType

site

  site-jsp


  class

info.magnolia.module.site.renderer.SiteAwareRendererWrapper

  wrappedRendererType

jsp

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.

NoScriptRenderer

The renderer for definitions without template scripts. Renders ContentMaps from components or component attribute from contextObjects.

PlainTextTemplateRenderer

Template renderer for plain text.

ResourcesBinaryRenderer

Streams the binary data stored in the content or loads it from an arbitrary path.

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.