Template definition

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.

Template definition types

Magnolia has three types of template definitions:

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

You can use common template properties in page, area and component definitions. Each template type has its own specific properties too.

Property Description


required for freemarker, optional for the SPA $type aliases (classes):

  • spa (info.magnolia.rendering.spa.renderer.SpaRenderableDefinition)

  • siteSpa (info.magnolia.rendering.spa.renderer.SiteAwareSpaRenderableDefinition`)

The property specifies which renderer should be used. Magnolia supports freemarker, spa and site-spa renderers by default.

If you have the Site module you can set renderType=site, then define a common templateScript in the template prototype to use on all pages of the site. For site-aware SPA rendering, the value is site-spa.


# 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: siteSpa
visible: true
dialog: mte:pages/pageProperties
baseUrl: http://localhost:3100/magnoliaAuthor
routeTemplate: '{{@path}}'
# templateScript: /vue-lm/webresources/dist/index.html

    renderType: spa
    title: Header
    type: single
        id: vue-lm:components/navigation
    renderType: spa
    title: Main
        id: vue-lm:components/title
        id: vue-lm:components/text-image
        id: vue-lm:components/component-with-area

You can also create a custom renderer.



Path to the template script as /<module>/templates/<type>/<file>.<ext> format. See Resources for more about script storage locations.

The property is not used in external SPA configurations. In this case, you must configure the baseUrl and, optionally, the routeTemplate properties.


required (in external SPA setups)

In an external SPA configuration, an external URL which the page editor iframe must point to.


# 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: spa
title: 'React: Contact'
# templateScript: /react-minimal-lm/webresources/build/index.html
baseUrl: http://example.com
dialog: spa-lm:pages/basic

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.


optional (in external SPA setups)

A format of a string appended to the baseUrl to initialize a page in an external SPA configuration.


# 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: spa
title: 'React: Contact'
# templateScript: /react-minimal-lm/webresources/build/index.html
baseUrl: http://localhost:3000
routeTemplate: '{{path}}?lang={language}'
dialog: spa-lm:pages/basic

Available properties

In addition to language, which is not a property in its own right, you can use any page node property, for example @name, @path, @id, or the prefixed mgnl:* jcr:* properties.

Double brackets vs single brackets

Double curly brackets and single curly brackets are interpreted differently. The parameter inside double curly brackets {{ }} will not be converted to the application/x-www-form-urlencoded MIME format.

+ In case you need to use path as a parameter or other parameters with characters such as space, +, ", %, <, >, \, ^ or other HTML-unsafe characters, use the single curly brackets.


Given that we have 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
  • routeTemplate:'?title={title}'

    Passing The string ü@foo-bar will generate a URI-safe form:



optional (in external SPA setups)

Implementation class of your own custom router so you can resolve extra attributes that must be added to the URL.



Dialog definition ID in <module-name>:<path to dialog definition> format.

The ID has two parts, separated by a colon:

  1. <module-name> : The name of the module which contains the dialog definition.

  2. <path>: Relative path to the dialog definition inside dialogs root item. For example the dialog ID my-module:pages/homePageProperties either points to the YAML file $magnolia.home/my-module/dialogs/homePageProperties.yaml or to the JCR node /modules/my-module/dialogs/homePageProperties in the configuration workspace.



Message bundle such as com.example.templates.messages. You don’t need to set this property if your message bundle is in the i18n directory (the mgnl-i18n directory in Magnolia 5.4.5 and earlier) inside the module. Magnolia will find the bundle automatically. Only set the property if you put the bundle somewhere else.



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:

  • Pages: Template dropdown in the Pages app.

  • Areas: Area toolbar in the page editor.

  • Components: Component toolbar in the page editor.



Template description displayed to editors. The value can be literal or retrieved from the message bundle (specified by i18nBasename) with a key.


required if the class property is not defined in the template definition.

An alias for the Java bean representing the definition data of this item. Use the following values:

  • page a for non-SPA template.

  • siteSpa for a site-aware SPA template.

  • spa for any other SPA-based template.



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: com.example.templates.CustomTemplateDefinition.

For an externally hosted SPA, the class is:
  • info.magnolia.rendering.spa.renderer.SpaRenderableDefinition, if $type: spa is not present in the template definition.

  • info.magnolia.rendering.spa.renderer.SiteAwareSpaRenderableDefinition, if $type: siteSpa is not present in the template definition.



A model class that contains business logic for the template. The class needs to implement the RenderingModel interface. The renderer creates a bean based on the modelClass. Current content, definition and the 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.


  • Java models: Fully-qualified class name. Example: com.example.templates.HomePageModel.

  • Groovy models: Path to the model using dot notation such as myModule.templates.components.LinkModel.



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.



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.

  example: my-value

To access the example parameter in a Freemarker script, use:


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:

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
        id: mtk2:components/textImage
        id: mtk2:components/linkList
Property Description



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 which contains the template definition.

  • <path>: Relative path to the template definition inside the templates folder. For example, the page ID my-module:pages/home either points to a YAML file $magnolia.resources.dir/my-module/templates/pages/home.yaml or to a JCR node /modules/my-module/templates/pages/home in the config workspace.

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.