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

A renderer is a Java class library that understands a particular templating language and produces text output.

Magnolia generates pages by merging a page definition with content from the repository.  This separation ensures that page structure and presentation remain consistent while content varies from page to page.

Magnolia includes a FreeMarker renderer. The Site module adds the the site renderer which provides site awareness.

You can add your own custom renderer. Velocity and Coldfusion have been successfully integrated.

What does a renderer do?

The renderer is the final step in the rendering process.

The renderer:

  • Creates the model
  • Gets context objects
  • Executes scripts
  • Produces output

Configuring a renderer

A renderer can be configured in the renderers folder of any module. All renderers are configured in the same way.

Context attributes

A renderer configuration supports a contextAttributes node (see examples below) under which your can register an unlimited number of templating functions classes. These classes define methods that you can use in your scripts. Methods are exposed in scripts using the value of the name property in the context attribute configuration. For example, cmsfn.decode method is used in FreeMarker scripts to escape HTML.The cmsfn part is the context attribute and decode is the templating method made available to the system by the TemplatingFunctions component class .

See Directives and Templating functions on how to use the directives and methods in your scripts.

FreeMarker renderer

FreemarkerRenderer is configured in /modules/rendering/renderers/freemarker.

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

 type

freemarker

Nodes and properties:

freemarkerFreeMarker renderer name.

contextAttributes

Map of registered context attributes.

<attribute name>

Arbitrary name. Typically matches the name property.

componentClass

Fully qualified class name. Each registered class adds useful templating functions for use in FreeMarker scripts.

name

Name of the context attribute used in templates to expose the functions.

class

info.magnolia.rendering.renderer.FreemarkerRenderer uses FreeMarker to render content.

type

Defines the render type. Used in FreeMarker template definitions for renderType property.

Site renderer

The Site module installs the site renderer that adds site awareness. Installation of the module adds:

  • The site renderer configuration
  • The sitefn context attributes to both the freemarker and site renderers.

The difference between the two renderers is the renderer class. SiteAwareFreemarkerRenderer adds template prototype functionality to sites.

The site renderer is configured in /modules/site/renderers/site.  

Node nameValue

 modules


 site


 renderers


 site


 contextAttributes


 cms


 cmsfn


 sitefn


 componentClass

info.magnolia.module.site.functions.SiteFunctions

 name

sitefn

 damfn


 catfn


 class

info.magnolia.module.site.renderer.SiteAwareFreemarkerRenderer

 type

site

Properties

class

info.magnolia.module.site.renderer.SiteAwareFreemarkerRenderer (Git) merges the definition of a template with the prototype template of a site.

name

Defines the site render type. Can be used as renderType in FreeMarker template definitions in a configured site.

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

Making your renderer site aware

Before 5.4.5, it was not possible to use the template prototype configured on a site when using renderType=freemarker on a template.

Now we have created a new wrapped renderer  - and there is no more need to implement a site aware renderer for your custom renderers. You can just useinfo.magnolia.module.site.renderer.SiteAwareRendererWrapper and let the property wrappedRendererType point to your custom renderer.

Example:

Node nameValue

 modules


 site


 renderers


 site


 class

 info.magnolia.module.site.renderer.SiteAwareRendererWrapper

 wrappedRendererType

freemarker

 site-jsp


 class

 info.magnolia.module.site.renderer.SiteAwareRendererWrapper

 wrappedRendererType

 jsp

 your-custom-site-renderer


 class

info.magnolia.module.site.renderer.SiteAwareRendererWrapper

 wrappedRendererType

 example-custom-renderer

The example-custom-renderer must be registered under /modules/rendering/renderers as any other renderer.

Node nameValue

 modules


 rendering


 renderers


 jsp


 freemarker


 example-custom-renderer


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


 filters


 IPConfig


 i18n


 security


 rendering


 freemarker


 templateExceptionHandler


 class

info.magnolia.freemarker.ModeDependentTemplateExceptionHandler