Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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 . 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:
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.
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:
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
Node name | Value |
---|---|
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 The renderer |
class | The fully qualified class name of the class that must implement the interface |
contextAttributes | A map to register components that are injected into the rendering context. The components can be used within the template scripts with their given names. |
| The fully qualified class name of the context attribute component. |
| The name of the component to add to the context. Use this name to reference the component in a template script. |
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.
Renderer | Provided by the module | Configuration |
---|---|---|
Freemarker renderer | magnolia-rendering |
/modules/rendering/renderers/freemarker
|
JSP renderer | magnolia-rendering |
/modules/rendering/renderers/jsp
|
Site aware renderer for freemarker | magnolia-site | /modules/site/renderers/site |
Site aware renderer for JSP | magnolia-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
.
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 .
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 registered in
/server/rendering/freemarker/templateExceptionHandler
. You can extend this class to fine-grain behavior.
Node name | Value |
---|---|
server | |
rendering | |
freemarker | |
templateExceptionHandler | |
class | info.magnolia.freemarker.ModeDependentTemplateExceptionHandler |
Use this renderer if your template scripts are written in JSP. The implementation class is .
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 . 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.
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.
The renderer for definitions without template scripts. Renders ContentMaps from components or component attribute from contextObjects. | |
Template renderer for plain text. | |
Streams the binary data stored in the content or loads it from an arbitrary path. |
To create your own renderer, extend . 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.