Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
A template definition gives a template a name and makes it available to the system. At a minimum a template definition must specify a script and a renderer. You can configure a template in a YAML file or a JCR node.
Template definition types
Magnolia has three types of template definitions:
- Page definition defines a page template. Pages are divided into areas.
- Area definition defines an area template. An area is configured in a page definition. Areas typically contain components.
- Component definition defines a component template.
The Magnolia CLI offers the create-page
and create-component
commands that automatically create basic scripts, template definitions and dialog definitions.
Common template properties
Simple template definition:
renderType: freemarker templateScript: /my-module/templates/pages/home.ftl dialog: my-module:pages/homePageProperties class: com.example.templates.CustomTemplateDefinition modelClass: com.example.templates.HomePageModel
Node name | Value |
---|---|
home | |
class | com.example.templates.CustomTemplateDefinition |
dialog | my-module:pages/homePageProperties |
modelClass | com.example.templates.HomePageModel |
renderType | freemarker |
templateScript | /my-module/templates/pages/home.ftl |
You can use common template properties in page, area and component definitions. Each template type has its own specific properties too.
| required Renderer to use. Magnolia supports If you have the Site module you can set You can also create a custom renderer. |
| required Path to the template script as |
| optional Dialog definition ID in The ID has two parts, separated by a colon:
|
i18nBasename
| optional Message bundle such as |
title
| optional Title of the template displayed to editors. The value can be literal or retrieved from a message bundle (which is defined in i18nBasename) with a key. Use alphanumeric characters in literal values. Displayed in:
|
description
| optional Template description displayed to editors. The value can be literal or retrieved from the message bundle (specified by |
| optional The fully-qualified class name for the Java bean representing the definition data of this item. The default class is TemplateDefinition . Only set the value when using custom definition class. Example: |
| optional A model class that contains business logic for the template. The model class needs to implement the
RenderingModel
interface. The renderer creates a bean based on the A Groovy model class can be referenced from a YAML template definition. Current limitations:
Value:
|
parameters | optional Custom template properties that you can access from a script without having to write a class. |
| optional, in JCR node configuration only Inherits the configuration from another template definition. The value is a valid Magnolia path. See Reusing configuration. |
variations | optional Merges template definition with the variation having the same name of the channel - if available. |
Custom template properties
Use a parameters
item in any template definition to add custom properties without having to write a custom class. Access the properties from your script using the def.parameters.<parameter-name>
notation. See def.
parameters: example: my-value
Node name | Value |
---|---|
<template name> | |
parameters | |
example | my-value |
To access the example
parameter in a Freemarker script, use:
${def.parameters.example!}
Referencing templates
Other configuration nodes can reference templates. The property used in the referencing configuration depends on the mechanism that is used.
Referencing templates with id property
The template id
property is used for:
- Component availability in an area definition.
- Template availability in a site definition.
Example: main
area definition referencing the MTK's textImage
and linkList
components in the availableComponents
node.
templateScript: /my-module/templates/pages/my-template.ftl renderType: freemarker areas: main: availableComponents: textImage: id: mtk:components/textImage linkList: id: mtk:components/linkList
Node name | Value |
---|---|
my-module | |
templates | |
pages | |
areas | |
main | |
availableComponents | |
textImage | |
id | mtk:components/textImage |
linkList | |
id | mtk:components/linkList |
Properties:
id | required ID of the template definition in The ID has two parts separated by a colon:
You can reference templates from any module |
The id
property is not a general property. It can only be used when it is supported by the referencing configuration.
Referencing templates using path
Various Magnolia mechanisms use the path to the template definition to reference templates. These mechanisms allow you to reuse configurations:
- Include mechanism: Is used in YAML definitions to include a referenced file. The Magnolia-specific
!include
directive uses the absolute path to reference the file. - Extends mechanism: Is used in JCR node configuration to extend another configuration. The
extends
property references the source configuration by its path. The target configuration inherits everything from the source and adds its own exceptions. - Definition decoration mechanism: Allows you to alter existing configured items, such as apps, dialogs, field types, templates and more.