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.
The Magnolia CLI offers the create-page and
create-component commands that automatically create basic scripts,
template definitions and dialog definitions.
Template properties
Magnolia natively supports template properties for rendering pages with FreeMarker or SPA. Some of the properties listed below are required or optional for both of these renderers, some are FreeMarker or SPA specific.
The property specifies which renderer to use. Magnolia supports the
freemarker, spa and site-spa renderers by default.
If you have the Site module,
you can set renderType to site and define a common templateScript in
the template
prototype to use for all pages on the site. For site-aware SPA rendering, the value is site-spa.
Dialog definition ID in <module-name>:<path to dialog definition>
format. The ID has two parts separated by a colon:
<module-name>: name of the module that contains the dialog definition.
<path>: relative path to the dialog definition inside the dialogs root
item. For example, the dialog ID my-module:pages/homePageProperties
points to either the YAML file
$magnolia.home/my-module/dialogs/homePageProperties.yaml or the JCR
node /modules/my-module/dialogs/homePageProperties in the
configuration workspace.
title
optional
Template title displayed to editors. The value can be literal or retrieved from a message bundle
with a key.
Use alphanumeric characters in literal values.
Template description displayed to editors. The value can be literal or retrieved from a message bundle
with a key.
Use alphanumeric characters in literal values.
$type
required if class is not defined in template definition
Alias for the Java bean representing the definition data of this item. Use the following values:
page for a non-SPA template.
siteSpa for a site-aware SPA template.
spa for any other SPA template.
class
optional
Fully qualified class name for the Java bean representing the
definition data of this item. The default class is
info.magnolia.rendering.template.TemplateDefinition.
Only set the value when using a custom definition class (for example,
com.example.templates.CustomTemplateDefinition).
Inherits the configuration from another template definition. The value
is a valid Magnolia path. See
Reusing configuration.
variations
optional
Allows you to deliver the same content in different formats. This helps you optimize content
for different channels (desktop, smartphone and tablet) and system parameters.
You can configure variations in the site definition as well as the template definition.
Alternatively, you may want to use personalization to create content variants.
SPA-only template properties
Property
Description
baseUrl
required
In an external SPA configuration, an external URL which the page editor iFrame must point to.
In an external SPA setup, multiple pages can have the same page definition but each page may need a different path or parameter to initialize. The format of this initialization element can be specified using the routeTemplate property.
routeTemplate
optional
Format of a string appended to baseUrl to initialize a page in an external SPA configuration.
Available properties
Besides language, you can use any page node property (for example, @name, @path, @id or the prefixed mgnl:* and jcr:* properties).
Double and single curly brackets
Double curly brackets and single curly brackets are interpreted differently. The parameter inside double curly brackets {{ }} is not
converted to the application/x-www-form-urlencoded MIME format. In case you need to use @path, other parameters with characters
such as space, +, ", %, <, >, \, ^ or any HTML-unsafe characters, use the single curly brackets.
Examples
With baseUrl: http://localhost:3000 and:
routeTemplate:'?title={{title}}'
Passing The string ü@foo-bar to title will result in a broken address:
http://localhost:3000/?title=The string ü@foo-bar
Copy
routeTemplate:'?title={title}'
Passing The string ü@foo-bar will generate a URI-safe form:
In an external SPA setup, the implementation class of your own custom router so you can resolve extra attributes that must be added to the URL.
FreeMarker-only template properties
Property
Description
templateScript
required
Path to the template script (in /<module>/templates/<type>/<file>.<ext> path format). See Resources for more about script
storage locations.
Since Magnolia 6.2.30, the property has been deprecated for use with the SPA renderer. In SPA context, configure the definition with baseUrl and optionally routeTemplate. For more details, see above in SPA-only template properties.
modelClass
optional
Model class that contains business logic for the template. The
class needs to implement the
info.magnolia.rendering.model.RenderingModel interface.
The renderer creates a bean based on modelClass. The current content,
definition and parent model are passed to the constructor. This
object is instantiated for each rendering of a page or component.
A Groovy model class can be referenced from a YAML template definition.
Current limitations
A Groovy model cannot be supplied as a file. You can only reference a
Groovy model stored in JCR. See the
Groovy
module.
The reference path cannot include the hyphen character.
Value
Java models: fully qualified class name (for example,
com.example.templates.HomePageModel).
Groovy models: path to the model using dot notation such as
myModule.templates.components.LinkModel.
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 Rendering context objects: def.
parameters:example:my-valueCopy
To access the example parameter in a FreeMarker script, use the following:
${def.parameters.example!}Copy
Referencing templates
Other configuration nodes can reference templates. The property used in
the referencing configuration depends on the mechanism used.
ID of the template definition in <module name>:<path to page definition> format.
The ID has two parts separated by a colon:
<module-name>: name of the module that contains the template definition.
<path>: relative path to the template definition inside the
templates folder. For example, the page ID my-module:pages/home
points to either the YAML file
$magnolia.resources.dir/my-module/templates/pages/home.yaml or the
JCR node /modules/my-module/templates/pages/home in the config
workspace.
You can reference templates from any module.
id 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: used in
YAML definitions to include a referenced file. The Magnolia-specific
!include directive uses the absolute path to reference the file.
Extends
mechanism: 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, fields, templates and more.
Configuration examples
SPA render type
With baseUrl property
# Since Magnolia 6.2.18, SPA $type aliases are available and the renderType property is optional.# class: info.magnolia.rendering.spa.renderer.SpaRenderableDefinition# renderType: spa$type:spatitle:'React: Contact'# templateScript: /react-minimal-lm/webresources/build/index.html# Since version 6.2.26 of the Pages module, the templateScript property is deprecated for use with the SPA renderer.baseUrl:http://example.comdialog:spa-lm:pages/basicCopy
With baseUrl and routeTemplate properties
# Since Magnolia 6.2.18, SPA $type aliases are available and the renderType property is optional.# class: info.magnolia.rendering.spa.renderer.SpaRenderableDefinition# renderType: spa$type:spatitle:'React: Contact'# templateScript: /react-minimal-lm/webresources/build/index.html# Since version 6.2.26 of the Pages module, the templateScript property is deprecated for use with the SPA renderer.baseUrl:http://localhost:3000routeTemplate:'{{path}}?lang={language}'dialog:spa-lm:pages/basicCopy
Site SPA render type
# Since Magnolia 6.2.18, SPA $type aliases are available and the parent renderType property is optional.# class: info.magnolia.rendering.spa.renderer.SiteAwareSpaRenderableDefinition# renderType: site-spa$type:siteSpavisible:truedialog:mte:pages/pagePropertiesbaseUrl:http://localhost:3100/magnoliaAuthorrouteTemplate:'{{@path}}'# templateScript: /vue-lm/webresources/dist/index.html# Since version 6.2.26 of the Pages module, the templateScript property is deprecated for use with the SPA renderer.areas:header:renderType:spatitle:Headertype:singleavailableComponents:navigation:id:vue-lm:components/navigationmain:renderType:spatitle:MainavailableComponents:title:id:vue-lm:components/titletext-image:id:vue-lm:components/text-imagecomponent-with-area:id:vue-lm:components/component-with-areaCopy